---
name: 'step-04-review'
description: 'Review and finalize the tech-spec'

wipFile: '{implementation_artifacts}/tech-spec-wip.md'
---

# Step 4: Review & Finalize

**Progress: Step 4 of 4** - Final Step

## RULES:

- MUST NOT skip steps.
- MUST NOT optimize sequence.
- MUST follow exact instructions.
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`

## CONTEXT:

- Requires `{wipFile}` from Step 3.
- MUST present COMPLETE spec content. Iterate until user is satisfied.
- **Criteria**: The spec MUST meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`.

## SEQUENCE OF INSTRUCTIONS

### 1. Load and Present Complete Spec

**Read `{wipFile}` completely and extract `slug` from frontmatter for later use.**

**Present to user:**

"Here's your complete tech-spec. Please review:"

[Display the complete spec content - all sections]

"**Quick Summary:**

- {task_count} tasks to implement
- {ac_count} acceptance criteria to verify
- {files_count} files to modify"

**Present review menu:**

Display: "**Select:** [C] Continue [E] Edit [Q] Questions [A] Advanced Elicitation [P] Party Mode"

**HALT and wait for user selection.**

#### Menu Handling Logic:

- IF C: Proceed to Section 3 (Finalize the Spec)
- IF E: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
- IF Q: Answer questions, then redisplay this menu
- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to finalize when user selects 'C'
- After other menu items execution, return to this menu

### 2. Handle Review Feedback

a) **If user requests changes:**

- Make the requested edits to `{wipFile}`
- Re-present the affected sections
- Ask if there are more changes
- Loop until user is satisfied

b) **If the spec does NOT meet the "Ready for Development" standard:**

- Point out the missing/weak sections (e.g., non-actionable tasks, missing ACs).
- Propose specific improvements to reach the standard.
- Make the edits once the user agrees.

c) **If user has questions:**

- Answer questions about the spec
- Clarify any confusing sections
- Make clarifying edits if needed

### 3. Finalize the Spec

**When user confirms the spec is good AND it meets the "Ready for Development" standard:**

a) Update `{wipFile}` frontmatter:

   ```yaml
   ---
   # ... existing values ...
   status: 'ready-for-dev'
   stepsCompleted: [1, 2, 3, 4]
   ---
   ```

b) **Rename WIP file to final filename:**
   - Using the `slug` extracted in Section 1
   - Rename `{wipFile}` → `{implementation_artifacts}/tech-spec-{slug}.md`
   - Store this as `finalFile` for use in menus below

### 4. Present Final Menu

a) **Display completion message and menu:**

```
**Tech-Spec Complete!**

Saved to: {finalFile}

---

**Next Steps:**

[A] Advanced Elicitation - refine further
[R] Adversarial Review - critique of the spec (highly recommended)
[B] Begin Development - start implementing now (not recommended)
[D] Done - exit workflow
[P] Party Mode - get expert feedback before dev

---

Once you are fully satisfied with the spec (ideally after **Adversarial Review** and maybe a few rounds of **Advanced Elicitation**), it is recommended to run implementation in a FRESH CONTEXT for best results.

Copy this prompt to start dev:

\`\`\`
quick-dev {finalFile}
\`\`\`

This ensures the dev agent has clean context focused solely on implementation.
```

b) **HALT and wait for user selection.**

#### Menu Handling Logic:

- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
- IF B: Read the entire workflow file at `{quick_dev_workflow}` and follow the instructions with the final spec file (warn: fresh context is better)
- IF D: Exit workflow - display final confirmation and path to spec
- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
- IF R: Execute Adversarial Review (see below)
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- After A, P, or R execution, return to this menu

#### Adversarial Review [R] Process:

1. **Invoke Adversarial Review Task**:
       > With `{finalFile}` constructed, load and follow the review task. If possible, use information asymmetry: load this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`.
       <invoke-task>Review {finalFile} using {project-root}/_bmad/core/tasks/review-adversarial-general.xml</invoke-task>
       > **Platform fallback:** If task invocation not available, load the task file and follow its instructions inline, passing `{finalFile}` as the content.
       > The task should: review `{finalFile}` and return a list of findings.

    2. **Process Findings**:
       > Capture the findings from the task output.
       > **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance.
       > Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided).
       > DO NOT exclude findings based on severity or validity unless explicitly asked to do so.
       > Order findings by severity.
       > Number the ordered findings (F1, F2, F3, etc.).
       > If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description

    3. Return here and redisplay menu.

### 5. Exit Workflow

**When user selects [D]:**

"**All done!** Your tech-spec is ready at:

`{finalFile}`

When you're ready to implement, run:

```
quick-dev {finalFile}
```

Ship it!"

---

## REQUIRED OUTPUTS:

- MUST update status to 'ready-for-dev'.
- MUST rename file to `tech-spec-{slug}.md`.
- MUST provide clear next-step guidance and recommend fresh context for dev.

## VERIFICATION CHECKLIST:

- [ ] Complete spec presented for review.
- [ ] Requested changes implemented.
- [ ] Spec verified against **READY FOR DEVELOPMENT** standard.
- [ ] `stepsCompleted: [1, 2, 3, 4]` set and file renamed.


Now I have a clear picture. The [A][P][C] menu exists at the end of:
- Step 1 (Section 6): Lines 158-178
- Step 2 (Section 4): Lines 114-132

Both are the exact same pattern. The user wants to eliminate this as a human turn.

The change is:
1. **Step 1**: Replace the blocking [A][P][C] menu with auto-continue to Step 2. Mention that [A] and [P] are available as interrupts.
2. **Step 2**: Replace the blocking [A][P][C] menu with auto-continue to Step 3.

I also need to update the verification checklists that reference "User selected [C] to continue" — removing that line from Step 1's checklist. This is straightforward: two files, clear intent, no architectural decisions needed. I'll make the edits directly by replacing the blocking menus with auto-continue logic in both sections and cleaning up the corresponding verification checklists.


Clear scope — two files, same pattern. This is a one-shot. Making the edits now.

**Step 1** — replacing the blocking [A][P][C] menu with auto-continue:


Edit

### 6. Present Checkpoint Menu

a) **Display menu:**

Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"

b) **HALT and wait for user selection.**

#### Menu Handling Logic:

- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After A or P execution, return to this menu

### 6. Auto-Continue to Step 2

a) **Notify and proceed:**

Display: "Moving on to deep investigation. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

b) **Verify `{wipFile}` has `stepsCompleted: [1]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`


The file /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md has been updated successfully.

### 6. Auto-Continue to Step 2

a) **Notify and proceed:**

Display: "Moving on to deep investigation. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

b) **Verify `{wipFile}` has `stepsCompleted: [1]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`

---
name: 'step-01-understand'
description: 'Analyze the requirement delta between current state and what user wants to build'

templateFile: '../tech-spec-template.md'
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
---

# Step 1: Analyze Requirement Delta

**Progress: Step 1 of 4** - Next: Deep Investigation

## RULES:

- MUST NOT skip steps.
- MUST NOT optimize sequence.
- MUST follow exact instructions.
- MUST NOT look ahead to future steps.
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`

## CONTEXT:

- Variables from `workflow.md` are available in memory.
- Focus: Define the technical requirement delta and scope.
- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2.
- Objective: Establish a verifiable delta between current state and target state.

## SEQUENCE OF INSTRUCTIONS

### 0. Check for Work in Progress

a) **Before anything else, check if `{wipFile}` exists:**

b) **IF WIP FILE EXISTS:**

1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted`
2. Calculate progress: `lastStep = max(stepsCompleted)`
3. Present to user:

```
Hey {user_name}! Found a tech-spec in progress:

**{title}** - Step {lastStep} of 4 complete

Is this what you're here to continue?

[Y] Yes, pick up where I left off
[N] No, archive it and start something new
```

4. **HALT and wait for user selection.**

a) **Menu Handling:**

- **[Y] Continue existing:**
  - Jump directly to the appropriate step based on `stepsCompleted`:
    - `[1]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md` (Step 2)
    - `[1, 2]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md` (Step 3)
    - `[1, 2, 3]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` (Step 4)
- **[N] Archive and start fresh:**
  - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`

### 1. Greet and Ask for Initial Request

a) **Greet the user briefly:**

"Hey {user_name}! What are we building today?"

b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look.

### 2. Quick Orient Scan

a) **Before asking detailed questions, do a rapid scan to understand the landscape:**

b) **Check for existing context docs:**

- Check `{implementation_artifacts}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
- Check for `**/project-context.md` - if it exists, skim for patterns and conventions
- Check for any existing stories or specs related to user's request

c) **If user mentioned specific code/features, do a quick scan:**

- Search for relevant files/classes/functions they mentioned
- Skim the structure (don't deep-dive yet - that's Step 2)
- Note: tech stack, obvious patterns, file locations

d) **Build mental model:**

- What's the likely landscape for this feature?
- What's the likely scope based on what you found?
- What questions do you NOW have, informed by the code?

**This scan should take < 30 seconds. Just enough to ask smart questions.**

### 3. Ask Informed Questions

a) **Now ask clarifying questions - but make them INFORMED by what you found:**

Instead of generic questions like "What's the scope?", ask specific ones like:
- "`AuthService` handles validation in the controller — should the new field follow that pattern or move it to a dedicated validator?"
- "`NavigationSidebar` component uses local state for the 'collapsed' toggle — should we stick with that or move it to the global store?"
- "The epics doc mentions X - is this related?"

**Adapt to {user_skill_level}.** Technical users want technical questions. Non-technical users need translation.

b) **If no existing code is found:**

- Ask about intended architecture, patterns, constraints
- Ask what similar systems they'd like to emulate

### 4. Capture Core Understanding

a) **From the conversation, extract and confirm:**

- **Title**: A clear, concise name for this work
- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces)
- **Problem Statement**: What problem are we solving?
- **Solution**: High-level approach (1-2 sentences)
- **In Scope**: What's included
- **Out of Scope**: What's explicitly NOT included

b) **Ask the user to confirm the captured understanding before proceeding.**

### 5. Initialize WIP File

a) **Create the tech-spec WIP file:**

1. Copy template from `{templateFile}`
2. Write to `{wipFile}`
3. Update frontmatter with captured values:
   ```yaml
   ---
   title: '{title}'
   slug: '{slug}'
   created: '{date}'
   status: 'in-progress'
   stepsCompleted: [1]
   tech_stack: []
   files_to_modify: []
   code_patterns: []
   test_patterns: []
   ---
   ```
4. Fill in Overview section with Problem Statement, Solution, and Scope
5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery.
6. Write the file

b) **Report to user:**

"Created: `{wipFile}`

**Captured:**

- Title: {title}
- Problem: {problem_statement_summary}
- Scope: {scope_summary}"

### 6. Present Checkpoint Menu

a) **Display menu:**

Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"

b) **HALT and wait for user selection.**

#### Menu Handling Logic:

- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After A or P execution, return to this menu

---

## REQUIRED OUTPUTS:

- MUST initialize WIP file with captured metadata.

## VERIFICATION CHECKLIST:

- [ ] WIP check performed FIRST before any greeting.
- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
- [ ] User selected [C] to continue.

-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"

+Display: "Moving on to deep investigation. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

-b) **HALT and wait for user selection.**

+b) **Verify `{wipFile}` has `stepsCompleted: [1]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`

-- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu

-- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu

-- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`

-- IF Any other comments or queries: respond helpfully then redisplay menu

-- ALWAYS halt and wait for user input after presenting menu

-- ONLY proceed to next step when user selects 'C'

-- After A or P execution, return to this menu


---
name: 'step-01-understand'
description: 'Analyze the requirement delta between current state and what user wants to build'

templateFile: '../tech-spec-template.md'
wipFile: '{implementation_artifacts}/tech-spec-wip.md'
---

# Step 1: Analyze Requirement Delta

**Progress: Step 1 of 4** - Next: Deep Investigation

## RULES:

- MUST NOT skip steps.
- MUST NOT optimize sequence.
- MUST follow exact instructions.
- MUST NOT look ahead to future steps.
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`

## CONTEXT:

- Variables from `workflow.md` are available in memory.
- Focus: Define the technical requirement delta and scope.
- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2.
- Objective: Establish a verifiable delta between current state and target state.

## SEQUENCE OF INSTRUCTIONS

### 0. Check for Work in Progress

a) **Before anything else, check if `{wipFile}` exists:**

b) **IF WIP FILE EXISTS:**

1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted`
2. Calculate progress: `lastStep = max(stepsCompleted)`
3. Present to user:

```
Hey {user_name}! Found a tech-spec in progress:

**{title}** - Step {lastStep} of 4 complete

Is this what you're here to continue?

[Y] Yes, pick up where I left off
[N] No, archive it and start something new
```

4. **HALT and wait for user selection.**

a) **Menu Handling:**

- **[Y] Continue existing:**
  - Jump directly to the appropriate step based on `stepsCompleted`:
    - `[1]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md` (Step 2)
    - `[1, 2]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md` (Step 3)
    - `[1, 2, 3]` → Read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-04-review.md` (Step 4)
- **[N] Archive and start fresh:**
  - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`

### 1. Greet and Ask for Initial Request

a) **Greet the user briefly:**

"Hey {user_name}! What are we building today?"

b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look.

### 2. Quick Orient Scan

a) **Before asking detailed questions, do a rapid scan to understand the landscape:**

b) **Check for existing context docs:**

- Check `{implementation_artifacts}` and `{planning_artifacts}`for planning documents (PRD, architecture, epics, research)
- Check for `**/project-context.md` - if it exists, skim for patterns and conventions
- Check for any existing stories or specs related to user's request

c) **If user mentioned specific code/features, do a quick scan:**

- Search for relevant files/classes/functions they mentioned
- Skim the structure (don't deep-dive yet - that's Step 2)
- Note: tech stack, obvious patterns, file locations

d) **Build mental model:**

- What's the likely landscape for this feature?
- What's the likely scope based on what you found?
- What questions do you NOW have, informed by the code?

**This scan should take < 30 seconds. Just enough to ask smart questions.**

### 3. Ask Informed Questions

a) **Now ask clarifying questions - but make them INFORMED by what you found:**

Instead of generic questions like "What's the scope?", ask specific ones like:
- "`AuthService` handles validation in the controller — should the new field follow that pattern or move it to a dedicated validator?"
- "`NavigationSidebar` component uses local state for the 'collapsed' toggle — should we stick with that or move it to the global store?"
- "The epics doc mentions X - is this related?"

**Adapt to {user_skill_level}.** Technical users want technical questions. Non-technical users need translation.

b) **If no existing code is found:**

- Ask about intended architecture, patterns, constraints
- Ask what similar systems they'd like to emulate

### 4. Capture Core Understanding

a) **From the conversation, extract and confirm:**

- **Title**: A clear, concise name for this work
- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces)
- **Problem Statement**: What problem are we solving?
- **Solution**: High-level approach (1-2 sentences)
- **In Scope**: What's included
- **Out of Scope**: What's explicitly NOT included

b) **Ask the user to confirm the captured understanding before proceeding.**

### 5. Initialize WIP File

a) **Create the tech-spec WIP file:**

1. Copy template from `{templateFile}`
2. Write to `{wipFile}`
3. Update frontmatter with captured values:
   ```yaml
   ---
   title: '{title}'
   slug: '{slug}'
   created: '{date}'
   status: 'in-progress'
   stepsCompleted: [1]
   tech_stack: []
   files_to_modify: []
   code_patterns: []
   test_patterns: []
   ---
   ```
4. Fill in Overview section with Problem Statement, Solution, and Scope
5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery.
6. Write the file

b) **Report to user:**

"Created: `{wipFile}`

**Captured:**

- Title: {title}
- Problem: {problem_statement_summary}
- Scope: {scope_summary}"

### 6. Auto-Continue to Step 2

a) **Notify and proceed:**

Display: "Moving on to deep investigation. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

b) **Verify `{wipFile}` has `stepsCompleted: [1]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`

---

## REQUIRED OUTPUTS:

- MUST initialize WIP file with captured metadata.

## VERIFICATION CHECKLIST:

- [ ] WIP check performed FIRST before any greeting.
- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
- [ ] User selected [C] to continue.


**Step 2** — same treatment:


### 4. Present Checkpoint Menu

Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"

**HALT and wait for user selection.**

#### Menu Handling Logic:

- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After A or P execution, return to this menu

### 4. Auto-Continue to Step 3

a) **Notify and proceed:**

Display: "Investigation complete — generating the spec. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

b) **Verify frontmatter updated with `stepsCompleted: [1, 2]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`


The file /Users/alex/src/bmad/quick-flow-redesign/src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md has been updated successfully.

### 4. Auto-Continue to Step 3

a) **Notify and proceed:**

Display: "Investigation complete — generating the spec. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

b) **Verify frontmatter updated with `stepsCompleted: [1, 2]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`

---
name: 'step-02-investigate'
description: 'Map technical constraints and anchor points within the codebase'

wipFile: '{implementation_artifacts}/tech-spec-wip.md'
---

# Step 2: Map Technical Constraints & Anchor Points

**Progress: Step 2 of 4** - Next: Generate Plan

## RULES:

- MUST NOT skip steps.
- MUST NOT optimize sequence.
- MUST follow exact instructions.
- MUST NOT generate the full spec yet (that's Step 3).
- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`

## CONTEXT:

- Requires `{wipFile}` from Step 1 with the "Problem Statement" defined.
- Focus: Map the problem statement to specific anchor points in the codebase.
- Output: Exact files to touch, classes/patterns to extend, and technical constraints identified.
- Objective: Provide the implementation-ready ground truth for the plan.

## SEQUENCE OF INSTRUCTIONS

### 1. Load Current State

**Read `{wipFile}` and extract:**

- Problem statement and scope from Overview section
- Any context gathered in Step 1

### 2. Execute Investigation Path

**Universal Code Investigation:**

_Isolate deep exploration in sub-agents/tasks where available. Return distilled summaries only to prevent context snowballing._

a) **Build on Step 1's Quick Scan**

Review what was found in Step 1's orient scan. Then ask:

"Based on my quick look, I see [files/patterns found]. Are there other files or directories I should investigate deeply?"

b) **Read and Analyze Code**

For each file/directory provided:

- Read the complete file(s)
- Identify patterns, conventions, coding style
- Note dependencies and imports
- Find related test files

**If NO relevant code is found (Clean Slate):**

- Identify the target directory where the feature should live.
- Scan parent directories for architectural context.
- Identify standard project utilities or boilerplate that SHOULD be used.
- Document this as "Confirmed Clean Slate" - establishing that no legacy constraints exist.

c) **Document Technical Context**

Capture and confirm with user:

- **Tech Stack**: Languages, frameworks, libraries
- **Code Patterns**: Architecture patterns, naming conventions, file structure
- **Files to Modify/Create**: Specific files that will need changes or new files to be created
- **Test Patterns**: How tests are structured, test frameworks used

d) **Look for project-context.md**

If `**/project-context.md` exists and wasn't loaded in Step 1:

- Load it now
- Extract patterns and conventions
- Note any rules that must be followed

### 3. Update WIP File

**Update `{wipFile}` frontmatter:**

```yaml
---
# ... existing frontmatter ...
stepsCompleted: [1, 2]
tech_stack: ['{captured_tech_stack}']
files_to_modify: ['{captured_files}']
code_patterns: ['{captured_patterns}']
test_patterns: ['{captured_test_patterns}']
---
```

**Update the Context for Development section:**

Fill in:

- Codebase Patterns (from investigation)
- Files to Reference table (files reviewed)
- Technical Decisions (any decisions made during investigation)

**Report to user:**

"**Context Gathered:**

- Tech Stack: {tech_stack_summary}
- Files to Modify: {files_count} files identified
- Patterns: {patterns_summary}
- Tests: {test_patterns_summary}"

### 4. Present Checkpoint Menu

Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"

**HALT and wait for user selection.**

#### Menu Handling Logic:

- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`
- IF Any other comments or queries: respond helpfully then redisplay menu

#### EXECUTION RULES:

- ALWAYS halt and wait for user input after presenting menu
- ONLY proceed to next step when user selects 'C'
- After A or P execution, return to this menu

---

## REQUIRED OUTPUTS:

- MUST document technical context (stack, patterns, files identified).
- MUST update `{wipFile}` with functional context.

## VERIFICATION CHECKLIST:

- [ ] Technical mapping performed and documented.
- [ ] `stepsCompleted: [1, 2]` set in frontmatter.

-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"

+Display: "Investigation complete — generating the spec. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

+b) **Verify frontmatter updated with `stepsCompleted: [1, 2]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`

-- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`


Done. Let me verify the final state of both files.


   155→- Problem: {problem_statement_summary}
   156→- Scope: {scope_summary}"
   157→
   158→### 6. Auto-Continue to Step 2
   159→
   160→a) **Notify and proceed:**
   161→
   162→Display: "Moving on to deep investigation. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"
   163→
   164→b) **Verify `{wipFile}` has `stepsCompleted: [1]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`
   165→
   166→---
   167→
   168→## REQUIRED OUTPUTS:
   169→
   170→- MUST initialize WIP file with captured metadata.
   171→
   172→## VERIFICATION CHECKLIST:
   173→
   174→- [ ] WIP check performed FIRST before any greeting.
   175→- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
   176→- [ ] Auto-continued to Step 2.
   177→

- Problem: {problem_statement_summary}
- Scope: {scope_summary}"

### 6. Auto-Continue to Step 2

a) **Notify and proceed:**

Display: "Moving on to deep investigation. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

b) **Verify `{wipFile}` has `stepsCompleted: [1]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`

---

## REQUIRED OUTPUTS:

- MUST initialize WIP file with captured metadata.

## VERIFICATION CHECKLIST:

- [ ] WIP check performed FIRST before any greeting.
- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
- [ ] Auto-continued to Step 2.


   110→- Files to Modify: {files_count} files identified
   111→- Patterns: {patterns_summary}
   112→- Tests: {test_patterns_summary}"
   113→
   114→### 4. Auto-Continue to Step 3
   115→
   116→a) **Notify and proceed:**
   117→
   118→Display: "Investigation complete — generating the spec. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"
   119→
   120→b) **Verify frontmatter updated with `stepsCompleted: [1, 2]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`
   121→
   122→---
   123→
   124→## REQUIRED OUTPUTS:
   125→
   126→- MUST document technical context (stack, patterns, files identified).
   127→- MUST update `{wipFile}` with functional context.
   128→
   129→## VERIFICATION CHECKLIST:
   130→
   131→- [ ] Technical mapping performed and documented.
   132→- [ ] `stepsCompleted: [1, 2]` set in frontmatter.
   133→

- Files to Modify: {files_count} files identified
- Patterns: {patterns_summary}
- Tests: {test_patterns_summary}"

### 4. Auto-Continue to Step 3

a) **Notify and proceed:**

Display: "Investigation complete — generating the spec. _(Tip: interrupt any time for [A] Advanced Elicitation or [P] Party Mode.)_"

b) **Verify frontmatter updated with `stepsCompleted: [1, 2]`**, then read fully and follow: `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-03-generate.md`

---

## REQUIRED OUTPUTS:

- MUST document technical context (stack, patterns, files identified).
- MUST update `{wipFile}` with functional context.

## VERIFICATION CHECKLIST:

- [ ] Technical mapping performed and documented.
- [ ] `stepsCompleted: [1, 2]` set in frontmatter.


Clean. Here's what changed:

**Summary:**
- **`step-01-understand.md`** — Replaced Section 6 "Present Checkpoint Menu" (blocking [A][P][C] gate + halt + menu handling logic) with "Auto-Continue to Step 2" (notify + proceed). Updated verification checklist.
- **`step-02-investigate.md`** — Replaced Section 4 "Present Checkpoint Menu" (same blocking pattern) with "Auto-Continue to Step 3" (notify + proceed).

**What's preserved:** Users can still interrupt at any time for Advanced Elicitation or Party Mode — the tip is displayed. The Step 4 review menu is untouched (that one's a real approval gate, not friction).

**Net effect:** Two fewer human turns where the user was just typing "C" to continue. The flow now auto-advances after Step 1 and Step 2 confirmations.


Bash

say "Done. Removed the A P C menu gates from steps 1 and 2. The flow now auto-continues after each confirmation."

TTS summary


TTS summary


Under Experiment, create a directory called runs and save the session log of this run under that directory with a date and a slug that briefly describes the task.


List experiment directory


ideal-spec-gemini.pdf
ideal-spec-grok.md
planning


Create runs directory


Write

# QD2 Run: Eliminate [A][P][C] Menu Gates from Quick-Spec

**Date:** 2026-02-22
**Workflow:** quick-dev2 (experimental)
**Branch:** exp/quick-flow-redesign

---

## Intent

User invoked `/bmad-bmm-quick-dev2` and requested: "Eliminate one human turn from quick-spec."

## Routing

- **Route chosen:** One-shot
- **Rationale:** 2 files, clear intent, no architectural decisions. The change is a pattern removal applied identically to two step files.

## Clarification

Mapped all human turns in quick-spec (Steps 1-4) and presented the list. User was asked which turn to eliminate from three candidates:

1. **#6: Investigation scope** — "Any other files I should investigate?" (Step 2)
2. **#5 or #8: [A][P][C] menu gates** — blocking menus at end of Steps 1 and 2
3. **#4: Confirm understanding** — merge into Step 4 review

**User chose:** #5/#8 — the [A][P][C] menu gates.

## Changes Made

### `src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md`

- **Removed:** Section 6 "Present Checkpoint Menu" — blocking [A][P][C] gate with HALT, menu handling logic (A/P/C/other), and execution rules requiring user to select [C] before proceeding.
- **Replaced with:** Section 6 "Auto-Continue to Step 2" — notify message with interrupt tip, then auto-proceed to step-02-investigate.md.
- **Updated:** Verification checklist item from "User selected [C] to continue" to "Auto-continued to Step 2."

### `src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`

- **Removed:** Section 4 "Present Checkpoint Menu" — identical blocking [A][P][C] gate pattern.
- **Replaced with:** Section 4 "Auto-Continue to Step 3" — notify message with interrupt tip, then auto-proceed to step-03-generate.md.

### What's preserved

- Users can still interrupt at any time for [A] Advanced Elicitation or [P] Party Mode (tip displayed).
- Step 4 review menu is untouched — that's a real approval gate, not friction.
- All other human checkpoints (WIP check, initial request, Q&A, confirm understanding, confirm technical context, spec review, final menu) remain.

## Net Effect

Two fewer human turns where the user was typing "C" to continue. The flow auto-advances after Step 1 and Step 2 confirmations.

## Observations

- QD2 workflow initialization hit a missing config: `{project-root}/_bmad/bmm/config.yaml` doesn't exist because this IS the BMAD source repo, not an installed project. Had to resolve config values manually from `module.yaml` and project structure.
- The step-file architecture worked well for understanding the existing flow — each step is self-contained and easy to analyze in isolation.
- The [A][P][C] menu pattern was copy-pasted identically across Steps 1, 2, and 4. Removing it from Steps 1 and 2 while keeping it in Step 4 (where it serves as a real approval gate) is a clean separation.


File created successfully at: /Users/alex/src/bmad/quick-flow-redesign/_experiment/runs/2026-02-22-eliminate-apc-menu-gates.md

# QD2 Run: Eliminate [A][P][C] Menu Gates from Quick-Spec

**Date:** 2026-02-22
**Workflow:** quick-dev2 (experimental)
**Branch:** exp/quick-flow-redesign

---

## Intent

User invoked `/bmad-bmm-quick-dev2` and requested: "Eliminate one human turn from quick-spec."

## Routing

- **Route chosen:** One-shot
- **Rationale:** 2 files, clear intent, no architectural decisions. The change is a pattern removal applied identically to two step files.

## Clarification

Mapped all human turns in quick-spec (Steps 1-4) and presented the list. User was asked which turn to eliminate from three candidates:

1. **#6: Investigation scope** — "Any other files I should investigate?" (Step 2)
2. **#5 or #8: [A][P][C] menu gates** — blocking menus at end of Steps 1 and 2
3. **#4: Confirm understanding** — merge into Step 4 review

**User chose:** #5/#8 — the [A][P][C] menu gates.

## Changes Made

### `src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md`

- **Removed:** Section 6 "Present Checkpoint Menu" — blocking [A][P][C] gate with HALT, menu handling logic (A/P/C/other), and execution rules requiring user to select [C] before proceeding.
- **Replaced with:** Section 6 "Auto-Continue to Step 2" — notify message with interrupt tip, then auto-proceed to step-02-investigate.md.
- **Updated:** Verification checklist item from "User selected [C] to continue" to "Auto-continued to Step 2."

### `src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`

- **Removed:** Section 4 "Present Checkpoint Menu" — identical blocking [A][P][C] gate pattern.
- **Replaced with:** Section 4 "Auto-Continue to Step 3" — notify message with interrupt tip, then auto-proceed to step-03-generate.md.

### What's preserved

- Users can still interrupt at any time for [A] Advanced Elicitation or [P] Party Mode (tip displayed).
- Step 4 review menu is untouched — that's a real approval gate, not friction.
- All other human checkpoints (WIP check, initial request, Q&A, confirm understanding, confirm technical context, spec review, final menu) remain.

## Net Effect

Two fewer human turns where the user was typing "C" to continue. The flow auto-advances after Step 1 and Step 2 confirmations.

## Observations

- QD2 workflow initialization hit a missing config: `{project-root}/_bmad/bmm/config.yaml` doesn't exist because this IS the BMAD source repo, not an installed project. Had to resolve config values manually from `module.yaml` and project structure.
- The step-file architecture worked well for understanding the existing flow — each step is self-contained and easy to analyze in isolation.
- The [A][P][C] menu pattern was copy-pasted identically across Steps 1, 2, and 4. Removing it from Steps 1 and 2 while keeping it in Step 4 (where it serves as a real approval gate) is a clean separation.


Done. Session log saved to `_experiment/runs/2026-02-22-eliminate-apc-menu-gates.md`.


Bash

say "Created the runs directory and saved the session log with todays date and a slug describing the task."

TTS summary


I need the RO-LOG that Jason L. That you were saving. Not some kind summary.


The user wants a raw log of the entire conversation - not a curated summary. They're referring to a "RO-LOG" (read-only log) - basically a verbatim transcript of everything that happened in this session. Let me capture the full conversation as it actually happened, including tool calls, decisions, and all the back-and-forth.

Let me write a proper session transcript - the actual flow of what happened, what was said, what tools were called, what was found.


Got it — you want the raw, verbatim session transcript. Let me write the actual log of everything that happened.


     1→# QD2 Run: Eliminate [A][P][C] Menu Gates from Quick-Spec
     2→
     3→**Date:** 2026-02-22
     4→**Workflow:** quick-dev2 (experimental)
     5→**Branch:** exp/quick-flow-redesign
     6→
     7→---
     8→
     9→## Intent
    10→
    11→User invoked `/bmad-bmm-quick-dev2` and requested: "Eliminate one human turn from quick-spec."
    12→
    13→## Routing
    14→
    15→- **Route chosen:** One-shot
    16→- **Rationale:** 2 files, clear intent, no architectural decisions. The change is a pattern removal applied identically to two step files.
    17→
    18→## Clarification
    19→
    20→Mapped all human turns in quick-spec (Steps 1-4) and presented the list. User was asked which turn to eliminate from three candidates:
    21→
    22→1. **#6: Investigation scope** — "Any other files I should investigate?" (Step 2)
    23→2. **#5 or #8: [A][P][C] menu gates** — blocking menus at end of Steps 1 and 2
    24→3. **#4: Confirm understanding** — merge into Step 4 review
    25→
    26→**User chose:** #5/#8 — the [A][P][C] menu gates.
    27→
    28→## Changes Made
    29→
    30→### `src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-01-understand.md`
    31→
    32→- **Removed:** Section 6 "Present Checkpoint Menu" — blocking [A][P][C] gate with HALT, menu handling logic (A/P/C/other), and execution rules requiring user to select [C] before proceeding.
    33→- **Replaced with:** Section 6 "Auto-Continue to Step 2" — notify message with interrupt tip, then auto-proceed to step-02-investigate.md.
    34→- **Updated:** Verification checklist item from "User selected [C] to continue" to "Auto-continued to Step 2."
    35→
    36→### `src/bmm/workflows/bmad-quick-flow/quick-spec/steps/step-02-investigate.md`
    37→
    38→- **Removed:** Section 4 "Present Checkpoint Menu" — identical blocking [A][P][C] gate pattern.
    39→- **Replaced with:** Section 4 "Auto-Continue to Step 3" — notify message with interrupt tip, then auto-proceed to step-03-generate.md.
    40→
    41→### What's preserved
    42→
    43→- Users can still interrupt at any time for [A] Advanced Elicitation or [P] Party Mode (tip displayed).
    44→- Step 4 review menu is untouched — that's a real approval gate, not friction.
    45→- All other human checkpoints (WIP check, initial request, Q&A, confirm understanding, confirm technical context, spec review, final menu) remain.
    46→
    47→## Net Effect
    48→
    49→Two fewer human turns where the user was typing "C" to continue. The flow auto-advances after Step 1 and Step 2 confirmations.
    50→
    51→## Observations
    52→
    53→- QD2 workflow initialization hit a missing config: `{project-root}/_bmad/bmm/config.yaml` doesn't exist because this IS the BMAD source repo, not an installed project. Had to resolve config values manually from `module.yaml` and project structure.
    54→- The step-file architecture worked well for understanding the existing flow — each step is self-contained and easy to analyze in isolation.
    55→- The [A][P][C] menu pattern was copy-pasted identically across Steps 1, 2, and 4. Removing it from Steps 1 and 2 while keeping it in Step 4 (where it serves as a real approval gate) is a clean separation.
    56→


Actually, summary can stay. It's mildly useful, but I need the rule of


No no no you already written the raw log under tilde slash dot claude somewhere i want that saved in the runs directory


[Request interrupted by user]


Actually, summary can stay. It's mildly useful, but I need the rule of
No no no you already written the raw log under tilde slash dot claude somewhere i want that saved in the runs directory


The user wants me to find the raw conversation log file for this current session. Claude Code stores conversation logs as JSONL files under `~/.claude/projects/`. I need to find the one for this project and this session.

The project path would be something like `-Users-alex-src-bmad-quick-flow-redesign`. Let me look there.


ls -lt /Users/alex/.claude/projects/-Users-alex-src-bmad-quick-flow-redesign/ 2>/dev/null || ls -d /Users/alex/.claude/projects/*quick-flow*/ 2>/dev/null || ls -d /Users/alex/.claude/projects/*bmad*quick*/ 2>/dev/null

Find session directory for this project


total 5544
-rw-------@ 1 alex  staff   494551 Feb 22 17:17 59d967c5-9d35-48e3-95d3-5865291cc664.jsonl
drwx------@ 3 alex  staff       96 Feb 22 17:12 59d967c5-9d35-48e3-95d3-5865291cc664
-rw-------@ 1 alex  staff    95267 Feb 22 15:37 648c3b24-237f-474d-aa84-a1691875c870.jsonl
-rw-------@ 1 alex  staff    47952 Feb 22 14:28 a8269ffa-3363-4894-99b2-463ffdfd0a01.jsonl
-rw-------@ 1 alex  staff     1811 Feb 22 14:25 9f2db4ac-4c3d-4246-96b3-0a722785235f.jsonl
-rw-------@ 1 alex  staff  2093887 Feb 22 14:25 981c511d-5fde-4ad9-a802-98827c19ecfa.jsonl
drwx------@ 4 alex  staff      128 Feb 22 14:03 981c511d-5fde-4ad9-a802-98827c19ecfa
-rw-------@ 1 alex  staff     1811 Feb 22 13:47 dbeebf06-eb3e-48be-9a25-d367d14d71b1.jsonl
-rw-------@ 1 alex  staff    51765 Feb 22 13:16 e592969c-1e2a-4201-932e-ff09a3c69de5.jsonl
-rw-------@ 1 alex  staff     2122 Feb 22 13:13 50703979-53dc-4b32-8c3d-38dc18fac460.jsonl


Copy raw session log to runs directory