spec.md

description	argument-hint
Start a brainstorming session to create a feature specification (Codex, no sub-agents)	<feature-name>

Feature Specification or Bug Investigation

Start a collaborative session for: $ARGUMENTS

Mode Detection

First, determine if this is a Feature Request or a Bug Report:

Bug indicators: Words like "bug", "error", "broken", "not working", "wrong", "incorrect", "fails", "crash", "issue", problem descriptions, error messages, unexpected behavior descriptions.

Feature indicators: Words like "add", "create", "implement", "new", "feature", capability descriptions.

---

MODE A: Bug Investigation

If this is a bug report, follow this flow:

Bug Investigation Instructions

1. Do Deep Investigation

Before writing anything, thoroughly investigate the bug:

• Search the codebase for relevant code using rg
• Read the relevant files to understand the current implementation
• Trace the data flow to understand how the bug might occur
• Check tests to see what behavior is expected
• Look for similar patterns elsewhere in the codebase
• Check recent git commits that might have introduced the issue

2. Create Bug Brainstorming File

Directory Naming with Auto-Increment:

1. Check specs/YYYY-MM-DD/ for existing directories
2. Find the highest number prefix (e.g., if 2-ui-foundation exists, next is 3)
3. If no directories exist, start with 0
4. Create: specs/YYYY-MM-DD/{N}-{{bug_name}}/brainstorming.md

Example: If specs/2026-01-06/ contains 0-roadmap/, 1-core-domain/, 2-ui-foundation/, the next bug would be 3-{{bug_name}}/

Use this structure:

# {{Bug Name}} - Investigation

**Date:** YYYY-MM-DD
**Status:** Investigating
**Reported Issue:** [Original bug description]

---

## 1. Bug Summary

**Symptom:** [What the user observed]
**Expected Behavior:** [What should happen]
**Actual Behavior:** [What actually happens]

---

## 2. Investigation Findings

### 2.1 Relevant Code Locations

| File | Line(s) | Purpose |
|------|---------|---------|
| `path/to/file.php` | 123-145 | Description |

### 2.2 Data Flow Analysis

[Trace how data flows through the system relevant to this bug]

### 2.3 Root Cause Analysis

**Hypothesis 1:** [Description]
- Evidence for: [...]
- Evidence against: [...]

**Hypothesis 2:** [Description]
- Evidence for: [...]
- Evidence against: [...]

**Most Likely Root Cause:** [Your assessment]

---

## 3. Fix Options

### Option A: [Name]
**Approach:** [Description]
**Pros:**
- [Pro 1]
**Cons:**
- [Con 1]
**Files to modify:**
- `path/to/file.php`
**Risk level:** Low/Medium/High

### Option B: [Name]
**Approach:** [Description]
**Pros:**
- [Pro 1]
**Cons:**
- [Con 1]
**Files to modify:**
- `path/to/file.php`
**Risk level:** Low/Medium/High

**Recommendation:** [Which option and why]

---

## 4. Clarifying Questions

[Questions that need user input before proceeding]

1. [Question 1]
2. [Question 2]

**Fabian's Comment:**

---

## 5. Reproduction Steps

[If identifiable, steps to reproduce]

1. Step 1
2. Step 2
3. Observe: [bug behavior]

---

## 6. Related Code & Tests

**Existing tests:** [List relevant test files]
**Similar implementations:** [Reference similar patterns in codebase]

3. Present Findings and Ask for Direction

After creating the brainstorming file, summarize your findings and wait for user input on:

• Which fix option to pursue
• Answers to clarifying questions
• Any additional context

4. If Proceeding to Fix

Once direction is confirmed, you can either:

• Create a -specification.md for complex fixes (follow Feature mode Section 10+)
• Proceed directly to implementation for simple fixes

---

MODE B: Feature Specification

If this is a feature request, follow the original feature brainstorming flow:

Core Principle: Complete Specifications

Every requirement must be explicit and verifiable. Use checkboxes for ALL requirements so completion can be objectively measured. Ambiguity leads to incomplete implementations.

Feature Instructions

1. Create Q&A File

Directory Naming with Auto-Increment:

1. Check specs/YYYY-MM-DD/ for existing directories
2. Find the highest number prefix (e.g., if 2-ui-foundation exists, next is 3)
3. If no directories exist, start with 0
4. Create: specs/YYYY-MM-DD/{N}-{{feature_name}}/brainstorming.md

Use today's date, the next available number, and the feature name from arguments (use hyphens for spaces in the folder name).

Example: If specs/2026-01-06/ contains 0-roadmap/, 1-core-domain/, 2-ui-foundation/, the next feature would be 3-{{feature_name}}/

2. Initialize the Conversation

Start the Q&A file with this header:

# {{Feature Name}} - Q&A Session

**Date:** YYYY-MM-DD
**Status:** Brainstorming

---

2b. Explore Codebase First

Before asking the first question, explore the codebase to find:

1. Similar features - Search for existing implementations that solve related problems
2. Patterns in use - Identify Actions, Flows, Services, Livewire components in the relevant domain
3. Database schema - Check existing tables and relationships that might be relevant
4. Test patterns - Look at how similar features are tested

Use this exploration to:

• Make informed recommendations during Q&A
• Reference existing patterns ("Similar to how X works...")
• Identify potential reuse opportunities
• Spot integration points early

Tools to use:

• rg for search
• mcp__laravel-boost__database-schema for existing tables
• rg --files for finding files in relevant directories

3. Begin with Vision Question

Write the first message asking about the general vision:

---

## Message 1: Understanding Your Vision

### The Feature

**My Current Understanding:**
[Brief summary of what you think this feature might be about based on the name]

**Questions:**
1. What problem does this feature solve?
2. Who will use this feature?
3. What does success look like?

**Fabian's Comment:**

---

4. Conversation Flow

For each subsequent message, follow this structure:

---

## Message N: [Topic]

### [Sub-topic 1]

**My Current Understanding:**
[What you understand so far about this aspect]

**Questions:** (if needed)
- Question 1?
- Question 2?

**Recommendation:** (if applicable)
[Your recommendation with brief reasoning]

**Fabian's Comment:**

---

### [Sub-topic 2]
...

IMPORTANT: After user responds to your message, you MUST:

1. Update brainstorming.md with their response
2. Regenerate specification.md (see Section 4b)
3. Then write your next message

4b. MANDATORY: Regenerate Specification After Each User Response

CRITICAL: After processing each user response, regenerate the specification file. DO NOT skip this step.

The specification represents the current "mental model" of the feature. It evolves from rough vision to detailed specs.

After each Q&A round:

1. Read the full brainstorming.md to gather all accumulated decisions
2. Regenerate specification.md completely with:
   • All confirmed decisions as concrete requirements
   • Undecided items marked with [TBD] or [PENDING: <specific question>]
   • Assumptions marked with [ASSUMPTION: <text>]
3. Update status in frontmatter based on completeness
4. Update completeness score - count defined vs total requirements

Status Progression (with Definition of Done):

Status	Done When
Draft - Initial Vision	Section 1 (Overview) complete: problem, value, users defined
Draft - Requirements Gathering	Section 2 complete: all FR-/NFR- concrete and verifiable
Draft - Architecture Design	Sections 3-4 complete: components, data flow, schema specified
Draft - Detailing	Sections 5-9 complete: phases, UI/UX, tests have file paths
Draft - QA Plan	Section 13 complete: acceptance criteria and manual test scenarios defined
Ready for Implementation	Zero markers remain, Open Questions table empty, 100% completeness

Marker Usage:

• [TBD] - General "to be determined"
• [PENDING: How should X handle Y?] - Specific question blocking this item
• [ASSUMPTION: Users will always have Z] - Assumption made, needs validation

5. Use Diagrams

When helpful, include ASCII diagrams or Mermaid diagrams to visualize:

• Data flow
• Component relationships
• User journeys
• Database schemas

Example:

**Architecture Concept:**
```mermaid
graph LR
    A[User] --> B[Livewire Component]
    B --> C[Action]
    C --> D[Service]

### 6. Decision Tracking

Once a decision is made on a topic, update the Q&A file by adding a "Decisions Summary" section after the header (if not present):

```markdown
## Decisions Summary

| Topic | Decision |
|-------|----------|
| **Topic Name** | Brief decision statement |

7. Follow-up Questions

When you need input on specific choices, format questions like this:

---

### Q1: [Topic Name]

[Brief context for the question]

- [ ] **A) Option 1** - Description
- [ ] **B) Option 2** - Description
- [ ] **C) Option 3** - Description

**Recommendation:** [Your recommendation]

**Fabian's Comment:**

8. Session Rules

• Always append to the file - Never delete previous conversation
• Mark user comments inline - When Fabian adds comments, they stay in the "Fabian's Comment:" sections
• Update status as the spec progresses (see Section 4b for status definitions)
• Read the full Q&A file before each response to maintain context
• Ask one thing at a time - Don't overwhelm with too many questions
• Spec reflects mental model - brainstorming.md is the conversation log; specification.md is the current state

CHECKLIST - Execute after EVERY user response:

[ ] 1. Read user's comments in brainstorming.md
[ ] 2. Update Decisions Summary table with new decisions
[ ] 3. REGENERATE specification.md with current state (Section 4b)
[ ] 4. Write next message to brainstorming.md

9. Wrapping Up Q&A

When no [TBD] or [PENDING] markers remain in the specification and completeness is 100%, update the status to Ready for Implementation.

10. Specification Template Reference

This template is used by Section 4b for iterative updates. The specification is regenerated after each Q&A round, evolving from rough vision to detailed implementation plan.

Create the specification at: specs/YYYY-MM-DD/{N}-{{feature_name}}/specification.md (same numbered directory as brainstorming.md)

The specification MUST contain the following sections with COMPLETE details.

CRITICAL FORMAT RULES:

1. ALL requirements MUST use checkboxes - Every single item that needs implementation gets a - [ ] checkbox
2. Requirements must be atomic - One checkbox = one verifiable action
3. No ambiguous language - Replace "should", "might", "could" with "must" or remove
4. Include file paths - Every implementation item should specify the file to create/modify
5. Group into phases - Each phase becomes one iteration during development
6. Acceptance criteria required - Each FR must have Given/When/Then criteria for testing

# {{Feature Name}} - Technical Specification

**Date:** YYYY-MM-DD
**Status:** Draft - Initial Vision
**Q&A Reference:** specs/YYYY-MM-DD/{N}-{{feature_name}}/brainstorming.md
**Completeness:** 0/0 requirements defined (0%)

---

## Open Questions

| # | Question | Blocks Section |
|---|----------|----------------|
| 1 | [Question from Q&A] | [Section #.#] |

*Status can only be "Ready for Implementation" when this table is empty and completeness is 100%.*

**Markers Legend:**
- `[TBD]` - To be determined, needs discussion
- `[PENDING: X]` - Specific question X must be answered first
- `[ASSUMPTION: X]` - Assumed to be true, validate with user

---

## 1. Overview

### 1.1 Feature Summary
[2-3 sentence description of what this feature does]

### 1.2 Business Value
[Why this feature matters, what problem it solves]

### 1.3 Target Users
[Who will use this feature and how]

---

## 2. Requirements

### 2.1 Functional Requirements

#### FR-1: [Requirement Name]
- [ ] **Requirement:** [What the system must do]
- **Acceptance Criteria:**
  - [ ] Given [context], when [action], then [expected result]
  - [ ] Given [context], when [action], then [expected result]

#### FR-2: [Requirement Name]
- [ ] **Requirement:** [What the system must do]
- **Acceptance Criteria:**
  - [ ] Given [context], when [action], then [expected result]

### 2.2 Non-Functional Requirements
- [ ] NFR-1: [Performance/Security/Scalability requirement]
- ...

### 2.3 Out of Scope
- [What this feature explicitly does NOT include]

### 2.4 Risks & Dependencies

| Risk | Impact | Mitigation | Owner |
|------|--------|------------|-------|
| [Risk description] | High/Medium/Low | [How to mitigate] | [TBD] |

**External Dependencies:**
- [ ] [Service/API name] - [What we need from it]

**Potential Blockers:**
- [Blocker description and resolution path]

---

## 3. Architecture

### 3.1 Component Overview
[Diagram and description of components involved]

### 3.2 Data Flow
[Step-by-step data flow through the system]

### 3.3 Dependencies
[External services, packages, existing components needed]

---

## 4. Database Schema

### 4.1 New Tables
[For each new table:]
```sql
CREATE TABLE table_name (
    -- columns with types and constraints
);

4.2 Table Modifications

[For each modified table:]

• Table: table_name
• Add column: column_name (type) - [reason]
• ...

4.3 Relationships

[Describe all relationships between models]

4.4 Indexes

[Any indexes needed for performance]

---

5. Implementation Steps

CRITICAL: Each phase = one development iteration. User invokes /dev {spec} continue for each phase.

5.1 Phase 1: [Phase Name]

Iteration scope: [Brief description of what this phase delivers]

Requirements (ALL must be checked off to complete this phase):

• REQ-1.1: Create migration database/migrations/YYYY_MM_DD_create_X_table.php
• REQ-1.2: Create model app/Models/X.php with relationships to Y, Z
• REQ-1.3: Create factory database/factories/XFactory.php with states: default, active, archived
• REQ-1.4: Create action app/Actions/Domain/DoSomething.php that [specific behavior]
• REQ-1.5: Write test tests/Feature/Actions/Domain/DoSomethingTest.php covering: [list scenarios]

Implementation Notes:

// Key code snippets or patterns to follow

5.2 Phase 2: [Phase Name]

Iteration scope: [Brief description]

Requirements:

• REQ-2.1: [Specific requirement with file path]
• REQ-2.2: [Specific requirement with file path]

5.3 Phase N: [Final Phase - Integration & Testing]

Iteration scope: Final integration and comprehensive testing

Requirements:

• REQ-N.1: All tests pass (php artisan test --parallel)
• REQ-N.2: Code style validated (vendor/bin/pint --dirty)
• REQ-N.3: Manual testing completed via Playwright

---

6. API / Interface Design

6.1 Routes

Method	Route	Controller/Action	Description
GET	/path	Controller@method	Description

6.2 Livewire Components

Component	Purpose	Key Properties	Key Methods
ComponentName	What it does	$props	methods()

6.3 Actions/Services

Class	Purpose	Input	Output
ActionName	What it does	Parameters	Return type

---

7. UI/UX Specification

7.1 Page/Component Layout

[ASCII diagram or description of layout]

7.2 User Interactions

1. User does X → System responds with Y
2. ...

7.3 States and Transitions

• Empty state: [description]
• Loading state: [description]
• Error state: [description]
• Success state: [description]

7.4 daisyUI Components to Use

• [component] for [purpose]
• ...

---

8. Testing Strategy

8.1 Unit Tests

Test File	Test Cases
tests/Unit/...	- test case 1
	- test case 2

8.2 Feature Tests

Test File	Test Cases
tests/Feature/...	- test case 1
	- test case 2

8.3 Critical Test Scenarios

1. Happy Path: [Description]
2. Edge Case: [Description]
3. Error Case: [Description]

8.4 Test Data Requirements

[Factories, seeders, or specific data needed]

---

9. Architecture Guidelines

9.1 Code Location

• Models: app/Models/
• Actions: app/Actions/{Domain}/
• Flows: app/Flows/
• Livewire: app/Livewire/{Domain}/
• Views: resources/views/livewire/{domain}/

9.2 Naming Conventions

• [Specific naming patterns for this feature]

9.3 Patterns to Follow

• [Reference existing similar implementations]
• [Specific patterns required]

9.4 Code Quality Rules

• [Any specific rules from CLAUDE.md that apply]

---

10. Validation & Completion Checklist

Per-Phase Completion (checked by dev/tree commands):

• All phase requirements implemented (checkboxes in Section 5)
• Architecture-guardian review passed
• Implementation-completeness-reviewer passed for phase
• Git commit created for phase

Final Completion (checked by /verify-complete command):

• ALL phases completed
• All tests pass (php artisan test --parallel)
• Code style validated (vendor/bin/pint --dirty)
• Manual testing via Playwright completed
• QA acceptance criteria from Section 13 verified by QA Analyst agent
• No gaps in -gaps.md file (or all addressed)

---

11. Notes & Decisions Log

[Copy all key decisions from the Q&A session here with context]

Decision	Rationale	Date
Decision 1	Why this was chosen	YYYY-MM-DD

---

12. Open Questions / Future Considerations

[Any items identified but deferred for later]

---

13. QA Acceptance Criteria & Manual Test Plan

This section defines how a QA Analyst (LLM-powered agent) will verify the feature using the browser, CLI, application logs, and database inspection. These are manual/exploratory checks - distinct from the automated Pest tests in Section 8.

13.1 Acceptance Criteria

Each criterion is a concrete, verifiable statement the QA agent can confirm through direct interaction with the running application.

#	Criterion	Verification Method
AC-1	[User can do X and sees Y]	Browser
AC-2	[Data is persisted correctly after action]	Database query
AC-3	[CLI command produces expected output]	CLI
AC-4	[No errors logged after flow completion]	Log inspection

13.2 Manual Test Plan

Pre-conditions

• Application is accessible at the site URL
• Required test data exists (seeded or created during test)
• User is authenticated as [role] (if applicable)

Test Scenarios

TS-1: [Happy Path - Primary Flow]

Goal: Verify the core feature works end-to-end as intended.

1. Navigate to [URL/page]
2. Perform [action]
3. Verify (browser): [expected UI result]
4. Verify (database): [expected data state via database-query]
5. Verify (logs): No errors in read-log-entries or browser-logs

TS-2: [Validation & Error Handling]

Goal: Verify the feature rejects invalid input gracefully.

1. Navigate to [URL/page]
2. Submit form with [invalid/empty/malformed data]
3. Verify (browser): Validation errors display correctly
4. Verify (database): No partial or corrupt data was saved

TS-3: [Edge Cases & Boundary Conditions]

Goal: Verify the feature handles unusual but valid scenarios.

1. [Scenario-specific steps]
2. Verify: [expected behavior]

TS-4: [Authorization & Access Control]

Goal: Verify unauthorized users cannot access or modify resources.

1. Attempt action as [unauthenticated user / wrong role]
2. Verify (browser): Access denied or redirect to login
3. Verify (database): No unauthorized changes

Post-conditions

• No new errors in application log (read-log-entries)
• No JavaScript console errors (browser-logs)
• Database state is consistent (no orphaned records, correct relationships)

13.3 QA Tools Reference

Tool	Use For
browser_navigate / browser_snapshot	Navigate pages and verify UI state
browser-logs	Check for JavaScript errors
read-log-entries	Check for PHP exceptions and application errors
database-query	Verify data persistence and integrity
tinker	Inspect model state or run assertions
get-absolute-url	Resolve correct application URLs

### 11. Critical Specification Review (Self-Validation)

After generating the specification, validate it yourself against the checklist:

- No logical inconsistencies between Q&A and specification
- All details discussed in Q&A are covered in the specification
- Implementation is technically feasible
- No scope creep beyond Q&A
- All requirements use checkbox format
- Requirements are atomic
- Each requirement specifies a file path
- Phases are clearly separated
- No `[TBD]`, `[PENDING]`, or `[ASSUMPTION]` markers remain
- Open Questions table is empty
- Completeness is 100%
- Section 13 has concrete acceptance criteria (not just placeholders)
- Manual test scenarios cover happy path, validation, edge cases, and authorization
- Each test scenario specifies verification method (browser, database, logs, CLI)

If gaps remain, fix the specification and re-validate.

### 12. Final User Review

After validation passes:

1. Present the specification to the user for review
2. Make any corrections requested
3. Update status to `Approved` when confirmed
4. Inform the user:

> "The technical specification is complete. To implement:
> - Use `/dev specs/YYYY-MM-DD/{N}-{{feature_name}}/specification.md` for each phase
> - After each phase, invoke `/dev {spec} continue` to proceed
> - When all phases complete, use `/verify-complete {spec}` for final validation"

**STOP HERE - DO NOT PROCEED TO IMPLEMENTATION**

The `/spec` command ends after presenting the specification. Do NOT:
- Start implementing the feature
- Run `/dev` automatically
- Create any implementation files
- Write any code

Wait for the user to explicitly invoke `/dev` to begin implementation.

---

Now create the Q&A file and begin the brainstorming session by asking about the vision for: **$ARGUMENTS**