sdlc-framework 1.0.0 → 1.0.1

package/src/workflows/discuss-phase.md

@@ -0,0 +1,395 @@
+<purpose>Drive AI-led brainstorming to transform a raw idea into a structured PRD. The discuss phase sits upstream of spec — it explores the problem space, researches unknowns inline, validates approaches, and builds requirements through targeted questioning. Without this phase, specs are built on assumptions instead of explored decisions.</purpose>
+<when_to_use>Run when the user has an idea but has not yet defined what to build. Also use when research is needed — external APIs, library choices, codebase patterns, best practices. This is pre-loop discovery — it feeds into /sdlc:spec. Can run at any point: before init, between loops, or when pivoting direction.</when_to_use>
+<required_reading>.sdlc/PROJECT.md (if exists), .sdlc/ROADMAP.md (if exists), .sdlc/research/*.md (prior research), codebase structure for technical context</required_reading>
+<loop_context>
+  expected_phase: DISCUSS (pre-loop activity)
+  prior_phase: any (entry point or between loops)
+  next_phase: SPEC (discuss always leads to spec)
+</loop_context>
+<process>
+
+<step name="seed_idea" priority="first">
+  The discussion needs a starting point — without one, questions are unfocused.
+
+  IF $ARGUMENTS provided:
+    Restate the idea in one sentence to confirm understanding.
+    Ask: "Is this what you want to explore, or should I adjust the framing?"
+
+  IF $ARGUMENTS empty:
+    Ask: "What idea, feature, or problem do you want to explore?"
+    Wait for response before proceeding.
+
+  IF .sdlc/PROJECT.md exists:
+    Read it. Note the tech stack, architecture, and constraints.
+    These inform all downstream questions — do not ask about things the project context already answers.
+
+  Record the seed idea for the decisions log.
+</step>
+
+<step name="explore_problem" priority="second">
+  Understanding the problem prevents building solutions to the wrong thing. Most failed features solve real problems badly because the problem was never properly defined.
+
+  Ask 2-4 questions from this category. Include a recommendation with each. Use AskUserQuestion.
+
+  PROBLEM QUESTIONS (pick the most relevant):
+  - "What specific problem does this solve? Who encounters it and how often?"
+    Recommendation: Frame the problem from the user's perspective, not the system's.
+  - "How do users solve this today? What makes current workarounds insufficient?"
+    Recommendation: Based on codebase scan, suggest what exists and what gaps you see.
+  - "What happens if this is not built? What is the cost of inaction?"
+    Recommendation: Assess severity based on what you know about the project.
+  - "Is this a new capability, an improvement to something existing, or a fix?"
+    Recommendation: Based on codebase, state whether related functionality already exists.
+
+  DO NOT ask questions whose answers are already in PROJECT.md or the codebase.
+  DO NOT ask questions that do not affect the technical solution.
+
+  Record all answers in the decisions log.
+</step>
+
+<step name="define_scope" priority="third">
+  Scope prevents building too much or too little. Without explicit scope, features creep and deadlines slip.
+
+  Ask 2-4 questions from this category. Include a recommendation with each.
+
+  SCOPE QUESTIONS (pick the most relevant):
+  - "What is the smallest version of this that delivers value? What is the full vision?"
+    Recommendation: Propose an MVP scope based on the problem definition.
+  - "What is explicitly NOT included? What should be deferred to later?"
+    Recommendation: Suggest boundaries based on complexity and dependencies.
+  - "Are there timeline or resource constraints that affect scope?"
+    Recommendation: If constraints exist, suggest what to cut first.
+  - "Does this interact with existing features? Which ones?"
+    Recommendation: Based on codebase scan, identify integration points.
+
+  After this round, you should be able to state the scope in one sentence.
+  Display: "Scope summary: {one sentence}. Does this match your intent?"
+
+  Record all answers in the decisions log.
+</step>
+
+<step name="research_unknowns" priority="fourth">
+  Unknowns discovered during problem and scope rounds must be resolved before choosing an approach. Picking an approach without understanding external APIs, library options, or codebase patterns leads to rework.
+
+  SKIP CONDITION: If no unknowns were identified in prior rounds — the idea is clear, the tech is familiar, and existing codebase patterns are sufficient — skip research and proceed to validate_approach.
+
+  A. IDENTIFY UNKNOWNS:
+  Review answers from explore_problem and define_scope. Extract unknowns:
+  - External APIs or services that need integration
+  - Library or tool choices not yet decided
+  - Codebase patterns not yet understood (how does X work in our code?)
+  - Best practices or security considerations for unfamiliar territory
+  - Migration paths or upgrade strategies
+
+  IF no unknowns identified:
+    Display: "No research needed — proceeding to approach validation."
+    Skip to validate_approach.
+
+  B. CLASSIFY RESEARCH TYPE:
+  For each unknown, classify:
+
+  TYPE: CODEBASE_EXPLORATION
+  Indicators: "how does X work in our code", "where is Y implemented", "what pattern does Z use", "find all instances of W"
+  Method: Codebase search agent (Grep, Glob, Read)
+
+  TYPE: WEB_RESEARCH
+  Indicators: "what is the best library for X", "how does Y technology work", "compare options for Z", "what are best practices for W"
+  Method: WebSearch agent
+
+  TYPE: HYBRID
+  Indicators: "how should we implement X" (needs both codebase understanding AND external knowledge)
+  Method: Both codebase and web agents
+
+  Display: "Unknowns identified: {list}. Research type: {type}. Spawning research subagents."
+
+  C. SPAWN RESEARCH SUBAGENTS:
+
+  For CODEBASE_EXPLORATION: spawn ONE Agent with run_in_background: true.
+  Agent instruction:
+  ```
+  You are researching the codebase to answer: "{research question}"
+
+  PROJECT CONTEXT:
+  {from PROJECT.md: tech stack, architecture, conventions}
+
+  YOUR TASK:
+  1. Search for files and code related to: {topic}
+     - Use Glob to find files by name pattern
+     - Use Grep to search file contents for relevant patterns
+     - Read key files to understand implementation details
+
+  2. For each relevant finding, record:
+     - File path and line numbers
+     - What the code does
+     - What pattern it follows
+     - How it relates to the research question
+
+  3. Look for:
+     - Existing implementations of similar features
+     - Patterns and conventions used in the codebase
+     - Utilities, helpers, and shared code that could be reused
+     - Test patterns used for similar features
+     - Configuration and setup patterns
+
+  4. Compile findings into a structured summary:
+     - Existing patterns found: {list with file references}
+     - Reusable code: {list of utilities/helpers that apply}
+     - Conventions: {naming, structure, testing patterns}
+     - Gaps: {what does NOT exist yet that would be needed}
+     - Recommendation: {how to approach the implementation based on existing patterns}
+  ```
+
+  For WEB_RESEARCH: spawn ONE Agent with run_in_background: true.
+  Agent instruction:
+  ```
+  You are researching an external topic to inform a specification.
+
+  RESEARCH QUESTION: "{research question}"
+
+  PROJECT CONTEXT:
+  {from PROJECT.md: tech stack — so research is relevant to the stack}
+
+  YOUR TASK:
+  1. Use WebSearch to find information about: {topic}
+  2. Search for:
+     - Official documentation for relevant libraries/tools
+     - Best practices and common patterns
+     - Comparison articles if evaluating options
+     - Known issues, gotchas, and caveats
+     - Security considerations
+
+  3. For each option/approach found:
+     - Name and description
+     - Pros: {advantages}
+     - Cons: {disadvantages}
+     - Maturity: {stable, beta, experimental}
+     - Community: {active, declining, abandoned}
+     - Compatibility with our stack: {yes/no, details}
+
+  4. Compile findings into a structured summary:
+     - Options evaluated: {list}
+     - Recommended option: {which and why}
+     - Key considerations: {trade-offs, risks}
+     - Implementation notes: {relevant details for the spec}
+  ```
+
+  For HYBRID: spawn TWO Agents (one codebase, one web) in parallel with run_in_background: true.
+
+  D. COLLECT AND SYNTHESIZE:
+  Wait for all agents to complete.
+
+  Synthesize findings:
+  - Are codebase patterns consistent with external best practices?
+  - Do any options conflict with existing conventions?
+  - Are there security or performance concerns?
+
+  E. SAVE FINDINGS:
+  Create .sdlc/research/ directory if it does not exist.
+  Generate a topic slug: lowercase, hyphens, no special characters, max 40 chars.
+
+  Write to .sdlc/research/{topic-slug}.md:
+  ```markdown
+  # Research: {topic}
+
+  ## Question
+  {Original research question}
+
+  ## Date
+  {ISO timestamp}
+
+  ## Type
+  {CODEBASE|WEB|HYBRID}
+
+  ## Codebase Findings
+  {Structured findings from codebase exploration}
+  - Pattern: {description} — {file}:{line}
+  - Reusable: {utility/helper} — {file}
+
+  ## External Findings
+  {Structured findings from web research}
+  - Option: {name} — Pros: {pros}, Cons: {cons}
+
+  ## Synthesis
+  {Combined analysis}
+
+  ## Recommendation
+  {What to do in the spec, and why}
+
+  ## References
+  - {file paths for codebase references}
+  - {URLs for web references}
+  ```
+
+  F. PRESENT FINDINGS:
+  Display synthesized findings to the user:
+  ```
+  Research Findings: {topic}
+
+  Codebase:
+  - Found {N} relevant patterns
+  - Key pattern: {description} (used in {files})
+  - Reusable: {list of utilities/helpers}
+  - Gap: {what is missing}
+
+  External:
+  - Recommended approach: {option}
+  - Key trade-off: {trade-off}
+  - Risk: {risk}
+
+  Saved: .sdlc/research/{topic-slug}.md
+  ```
+
+  These findings feed directly into the next step — approach validation.
+</step>
+
+<step name="validate_approach" priority="fifth">
+  Choosing the wrong approach is the most expensive mistake — it compounds through every downstream phase. Presenting options with trade-offs prevents blind commitment to the first idea.
+
+  Based on the problem, scope, and research findings (if any), identify 2-3 viable technical approaches.
+
+  IF research was conducted in research_unknowns:
+    Use research findings to inform approach options. Reference specific findings — do not ignore the research.
+    Approaches that conflict with codebase patterns or external best practices must note the conflict.
+
+  Present each approach:
+  ```
+  Approach A (recommended): {description}
+  - Effort: {low/medium/high}
+  - Risk: {what could go wrong}
+  - Maintenance: {ongoing burden}
+  - Fits existing patterns: {yes/no — reference specific codebase patterns}
+  - Research support: {what research findings support this approach}
+
+  Approach B: {description}
+  - Effort: {low/medium/high}
+  - Risk: {what could go wrong}
+  - Maintenance: {ongoing burden}
+  - Fits existing patterns: {yes/no}
+
+  Approach C (do nothing / defer): {description}
+  - Risk of deferring: {what happens}
+  ```
+
+  Ask: "Which approach do you prefer? I recommend Approach A because {concrete reason}."
+
+  IF the user picks a non-recommended approach:
+    Acknowledge the choice. Do not argue. Record the rationale.
+
+  IF the user is unsure:
+    Ask one targeted follow-up to resolve the uncertainty.
+
+  Record the chosen approach and rationale in the decisions log.
+</step>
+
+<step name="detail_requirements" priority="sixth">
+  Requirements bridge the gap between "what to build" and "how to spec it." Missing requirements surface as bugs during implementation.
+
+  Ask 2-4 questions from this category. Include a recommendation with each.
+
+  REQUIREMENTS QUESTIONS (pick the most relevant):
+  - "Walk me through the primary user flow. What does the user do step by step?"
+    Recommendation: Propose a flow based on the chosen approach.
+  - "What are the edge cases? What happens when {unlikely but possible scenario}?"
+    Recommendation: List 2-3 edge cases you identified and propose handling.
+  - "Are there security, performance, or accessibility requirements?"
+    Recommendation: Based on project context, suggest relevant NFRs.
+  - "How will you know this works? What does success look like?"
+    Recommendation: Propose measurable success criteria.
+  - "What data does this feature need? New models, fields, or API endpoints?"
+    Recommendation: Based on codebase, suggest data model approach.
+
+  STOP ASKING SIGNAL:
+  - You can write functional requirements for the core flow.
+  - You can list at least 3 edge cases with expected behavior.
+  - You know the primary user flow end to end.
+  - Remaining unknowns are implementation details, not requirements.
+
+  IF clarity is sufficient after round 2 or 3, skip this round and proceed to compile.
+
+  Record all answers in the decisions log.
+</step>
+
+<step name="compile_prd" priority="seventh">
+  The PRD is the deliverable — it captures every decision made during discussion and every research finding discovered. Without it, the discussion is just a conversation that evaporates.
+
+  Create .sdlc/discuss/ directory if it does not exist.
+
+  Generate a topic slug from the seed idea: lowercase, hyphens, no special characters, max 40 chars.
+
+  Write .sdlc/discuss/{topic-slug}-PRD.md using the PRD template structure:
+  - Problem Statement: from explore_problem answers
+  - Proposed Solution: from validate_approach chosen approach
+  - Alternatives Considered: from validate_approach rejected approaches
+  - Research Findings: from research_unknowns findings (if research was conducted)
+    - Codebase patterns discovered
+    - External options evaluated
+    - Recommendation and rationale
+    - Link to full research: .sdlc/research/{topic-slug}.md
+  - Requirements: from detail_requirements answers
+  - Constraints: from define_scope answers
+  - Edge Cases: from detail_requirements answers
+  - Success Metrics: from detail_requirements answers
+  - Decisions Log: every question asked and answer received, numbered
+
+  IF research was NOT conducted:
+    Omit the Research Findings section entirely.
+
+  Display a compact summary of the PRD (30-50 lines):
+  - Problem (2 lines)
+  - Solution (2 lines)
+  - Research findings (2-3 lines, if applicable)
+  - Requirements (numbered list)
+  - Constraints (list)
+  - Edge cases (list)
+  - Open questions (list)
+</step>
+
+<step name="approve_and_route" priority="eighth">
+  The user must approve the PRD before it feeds into spec. An unapproved PRD is just notes.
+
+  Ask: "PRD complete. Review the summary above."
+  Present options:
+  - APPROVE: Lock the PRD and proceed to /sdlc:spec
+  - REVISE: Tell me what to change (re-compile after changes)
+  - REJECT: Discard the PRD and stop
+
+  IF APPROVE:
+    Set PRD status to APPROVED.
+    Update .sdlc/STATE.md:
+    - Add history entry: "{timestamp} | discuss | Topic: {topic}. PRD saved. Research: {yes/no}."
+    - Set next_required_action: /sdlc:spec
+    - Add prd_path: .sdlc/discuss/{topic-slug}-PRD.md
+
+    Display:
+    ```
+    PRD approved.
+
+    Saved: .sdlc/discuss/{topic-slug}-PRD.md
+    Research: {.sdlc/research/{topic-slug}.md if applicable, otherwise "none"}
+
+    The spec phase will use this PRD to create a detailed specification with
+    acceptance criteria and task dependencies.
+
+    NEXT: /sdlc:spec
+    ```
+
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:spec.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:spec"
+      Wait for user to manually run the command.
+    </auto_advance>
+
+  IF REVISE:
+    Apply changes. Re-display summary. Re-ask for approval.
+
+  IF REJECT:
+    Delete the PRD file. Display: "PRD discarded." Stop.
+</step>
+
+</process>

package/src/workflows/fast-forward.md

@@ -1,10 +1,10 @@
-<purpose>The universal entry point workflow. Accept a plain language description, classify the work, estimate complexity, and either execute inline (simple work) or route to the appropriate specialized command (complex work, bugs, research, hotfixes). This is the "just tell me what to do" workflow.</purpose>
+<purpose>The universal entry point workflow. Accept a plain language description, classify the work, estimate complexity, and either execute inline (simple work), handle critical issues as inline hotfixes, or route to the appropriate specialized command. This is the "just tell me what to do" workflow.</purpose>
 <when_to_use>Use anytime. This is the default way to start work. The user describes what they need, and this workflow figures out the rest. No prior knowledge of SDLC commands required.</when_to_use>
 <required_reading>.sdlc/STATE.md, .sdlc/PROJECT.md, .sdlc/LAWS.md</required_reading>
 <loop_context>
-  expected_phase: FAST (compressed loop or routing)
+  expected_phase: FAST (compressed loop, inline hotfix, or routing)
   prior_phase: any (fast can be used between loops or as the first action)
-  next_phase: depends on routing — SPEC, DEBUG, HOTFIX, RESEARCH, or self-contained
+  next_phase: depends on routing — SPEC, DEBUG, DISCUSS, or self-contained
 </loop_context>
 <references>
 @~/.claude/sdlc-framework/references/prompt-detection.md
@@ -49,10 +49,9 @@
 
   1. CRITICAL — urgent production issues
      Indicators: "urgent", "production", "down", "outage", "critical", "P0", "hotfix", "emergency", "ASAP"
-     Route: /sdlc:hotfix
-     Display: "Critical issue detected. Routing to /sdlc:hotfix for emergency handling."
-     Write to STATE.md: fast_context = {original description}
-     STOP this workflow.
+     Route: inline hotfix (skip to inline_hotfix step)
+     Display: "Critical issue detected. Running inline hotfix — minimal spec, full verification."
+     Do NOT stop — proceed to inline_hotfix step.
 
   2. BUG — something broken that needs debugging
      Indicators: "fix bug", "broken", "crash", "error when", "fails to", "wrong output", "regression", "not working", "throws", "exception"
@@ -62,13 +61,39 @@
      - No → FEATURE (a "fix" that is really a refinement)
      Display: "Bug detected. Routing to /sdlc:debug for structured debugging."
      Write to STATE.md: fast_context = {original description}
+
+     <auto_advance>
+     Read .sdlc/STATE.md auto_advance setting.
+     IF auto_advance is true:
+       Display: "Auto-advancing to /sdlc:debug in {advance_delay_seconds}s — reply to intervene."
+       Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+       If no user message received during sleep: automatically execute /sdlc:debug.
+       If user sends a message: cancel auto-advance, process user input, then resume.
+     IF auto_advance is false:
+       Display: "NEXT ACTION REQUIRED: /sdlc:debug"
+       Wait for user to manually run the command.
+     </auto_advance>
+
      STOP this workflow.
 
-  3. RESEARCH — exploration and investigation
-     Indicators: "explore", "investigate", "research", "compare options", "evaluate", "what are the options", "how does X work", "should we use"
-     Route: /sdlc:research
-     Display: "Research task detected. Routing to /sdlc:research."
+  3. DISCUSS — brainstorming, research, and exploration
+     Indicators: "brainstorm", "discuss", "idea", "what if", "think about", "concept", "should we", "could we", "explore", "investigate", "research", "compare options", "evaluate", "what are the options", "how does X work", "should we use"
+     Route: /sdlc:discuss
+     Display: "Brainstorming or research topic detected. Routing to /sdlc:discuss for structured discovery."
      Write to STATE.md: fast_context = {original description}
+
+     <auto_advance>
+     Read .sdlc/STATE.md auto_advance setting.
+     IF auto_advance is true:
+       Display: "Auto-advancing to /sdlc:discuss in {advance_delay_seconds}s — reply to intervene."
+       Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+       If no user message received during sleep: automatically execute /sdlc:discuss.
+       If user sends a message: cancel auto-advance, process user input, then resume.
+     IF auto_advance is false:
+       Display: "NEXT ACTION REQUIRED: /sdlc:discuss"
+       Wait for user to manually run the command.
+     </auto_advance>
+
      STOP this workflow.
 
   4. FEATURE — new functionality
@@ -92,7 +117,7 @@
 
   Display: "Classified as: {TYPE}. {Brief explanation of why.}"
 
-  WHY: Classification determines the entire routing strategy. Bugs need root cause analysis (debug), not fast implementation. Critical issues need minimal ceremony (hotfix). Research needs subagents, not code changes. Getting the classification wrong wastes the user's time on the wrong workflow.
+  WHY: Classification determines the entire routing strategy. Bugs need root cause analysis (debug), not fast implementation. Critical issues need minimal ceremony (hotfix). Research and brainstorming need structured discovery (discuss). Getting the classification wrong wastes the user's time on the wrong workflow.
 </step>
 
 <step name="estimate_complexity" priority="third">
@@ -176,10 +201,21 @@
   Your description and the identified files have been saved to STATE.md.
   /sdlc:spec will pick up this context automatically — no need to repeat yourself.
 
-  NEXT ACTION REQUIRED: /sdlc:spec
-  Run /sdlc:spec to decompose this into parallel tasks with proper dependency ordering.
+  NEXT: /sdlc:spec
   ```
 
+  <auto_advance>
+  Read .sdlc/STATE.md auto_advance setting.
+  IF auto_advance is true:
+    Display: "Auto-advancing to /sdlc:spec in {advance_delay_seconds}s — reply to intervene."
+    Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+    If no user message received during sleep: automatically execute /sdlc:spec.
+    If user sends a message: cancel auto-advance, process user input, then resume.
+  IF auto_advance is false:
+    Display: "NEXT ACTION REQUIRED: /sdlc:spec — Run /sdlc:spec to decompose this into parallel tasks with proper dependency ordering."
+    Wait for user to manually run the command.
+  </auto_advance>
+
   STOP this workflow.
 
   WHY: The user should not have to re-describe their work when routing. Pre-filling context makes the handoff seamless. The explanation tells the user WHY the routing happened — building trust in the framework's decisions.
@@ -276,7 +312,7 @@
   - PASS: expected outcome observed
   - FAIL: expected outcome not observed, describe what happened instead
 
-  IF ALL PASS: proceed to mini-review
+  IF ALL PASS: proceed to mini-laws-review
   IF ANY FAIL:
     Display: "Verification failed:\n  AC-{N}: FAIL — {what happened}\nFix the issue and describe what you changed, or say 'retry' to re-verify."
     Wait for user response, then re-verify.
@@ -337,4 +373,56 @@
   WHY: Fast is a side-quest. It records what happened (audit trail) but does not disrupt the main loop state.
 </step>
 
+<step name="inline_hotfix" priority="tenth">
+  ONLY IF classification = CRITICAL. Emergency fix with minimal ceremony, maximum verification.
+
+  A. TRIAGE:
+  Ask 3 questions:
+  - "What is broken? (specific symptom)"
+  - "What is the impact? (who is affected)"
+  - "When did it start? (recent deploy, config change)"
+
+  Classify severity:
+  - P0: system down, critical path unavailable
+  - P1: data corruption, security breach, data loss
+  - P2: major feature broken but system is up
+
+  If not P0/P1: Display "This may not be critical. Consider /sdlc:debug instead." Let user override.
+
+  Save current STATE.md position — hotfix restores it when done.
+
+  B. 3-LINE INLINE SPEC:
+  - Line 1: WHAT is broken (from triage)
+  - Line 2: WHERE is the likely location (quick Grep search)
+  - Line 3: WHAT the fix should achieve (expected behavior)
+  Display but do NOT wait for approval — speed matters.
+  Boundary: fix ONLY the critical issue. No refactoring. No cleanup.
+
+  C. FIX DIRECTLY:
+  - Single-threaded, no sub-agents
+  - Read relevant files, apply MINIMAL fix
+  - Engineering laws still apply (no empty catch, no hardcoded secrets)
+  - Add regression test for the specific failure
+  - Mark debt with TODO(hotfix-{date})
+
+  D. FULL VERIFICATION:
+  - Run FULL test suite (all tests, not just affected)
+  - For UI: Playwright verification
+  - If any fail: fix before proceeding
+
+  E. FULL REVIEW:
+  - Check all modified files against engineering laws
+  - Security blockers still block even in emergencies
+  - Warnings acceptable for hotfixes
+
+  F. RECORD:
+  - Hotfix number = {phase}.{count+1} (e.g., 02.1, 02.2)
+  - Create .sdlc/phases/{phase}/HOTFIX-{number}-SUMMARY.md
+  - Update STATE.md: restore prior state, add history entry
+  - Update ROADMAP.md: note hotfix under current phase
+  - Display completion summary with verification results
+
+  WHY: Hotfixes trade planning ceremony for speed, but never trade verification. The inline approach avoids command-switching overhead during emergencies while maintaining quality gates.
+</step>
+
 </process>

package/src/workflows/fix-findings.md

@@ -1,15 +1,15 @@
-<purpose>Systematically fix all blocker findings from code review. Read REVIEW.md, analyze fix dependencies, apply fixes in optimal order (parallel where possible), then re-run review to confirm compliance. Fixes must not introduce new violations.</purpose>
-<when_to_use>Run after /sdlc:review reports blockers. STATE.md should show next_required_action = /sdlc:review (still in review loop) with blockers outstanding.</when_to_use>
-<required_reading>.sdlc/STATE.md, the current REVIEW.md, .sdlc/LAWS.md, all files referenced in findings</required_reading>
+<purpose>Systematically fix all blocker findings from verification. Read VERIFY.md Phase 2 section, analyze fix dependencies, apply fixes in optimal order (parallel where possible), then re-run verify to confirm compliance. Fixes must not introduce new violations.</purpose>
+<when_to_use>Run after /sdlc:verify reports code quality blockers. STATE.md should show next_required_action = /sdlc:fix with blockers outstanding.</when_to_use>
+<required_reading>.sdlc/STATE.md, the current VERIFY.md, .sdlc/LAWS.md, all files referenced in findings</required_reading>
 <loop_context>
-  expected_phase: REVIEW (fix sub-loop)
-  prior_phase: REVIEW found blockers
-  next_phase: REVIEW (re-run) → CLOSE (if pass)
+  expected_phase: VERIFY (fix sub-loop)
+  prior_phase: VERIFY found blockers
+  next_phase: VERIFY (re-run) → CLOSE (if pass)
 </loop_context>
 <process>
 
 <step name="load_findings" priority="first">
-  Read the REVIEW.md at .sdlc/phases/{current_phase}/{current_plan}-REVIEW.md.
+  Read the VERIFY.md at .sdlc/phases/{current_phase}/{current_plan}-VERIFY.md. Parse the Phase 2 (Engineering Laws Review) section.
 
   Parse every finding into a structured list:
   ```
@@ -25,7 +25,7 @@
   Count totals: {blocker_count} blockers, {warning_count} warnings, {info_count} info.
 
   IF blocker_count == 0:
-    Display: "No blockers to fix. Run /sdlc:review to confirm, then /sdlc:close."
+    Display: "No blockers to fix. Run /sdlc:verify to confirm, then /sdlc:close."
     STOP.
 
   WHY: Parsing findings into structured data enables dependency analysis and parallel execution. Without structure, fixes would be ad-hoc and error-prone.
@@ -193,9 +193,9 @@
     Show which fix likely caused the regression.
     STOP.
 
-  IF all pass: proceed to re-review.
+  IF all pass: proceed to re-verify.
 
-  WHY: Fixes must not break the project. The build/test check is a safety net before re-running review.
+  WHY: Fixes must not break the project. The build/test check is a safety net before re-running verify.
 </step>
 
 <step name="trigger_re_review" priority="eighth">
@@ -209,27 +209,50 @@
   - Build: ✓
   - Tests: ✓
 
-  Re-running /sdlc:review to confirm compliance...
+  Re-running /sdlc:verify to confirm compliance...
   ```
 
-  Trigger the review-phase workflow (re-run the full review).
+  Trigger the verify-phase workflow (re-run the full verification including AC tests and engineering laws review).
 
-  IF re-review finds NEW blockers (fixes introduced new violations):
-    Display: "Fix introduced {N} new blockers. Review the new findings and run /sdlc:fix again."
+  IF re-verify finds NEW blockers (fixes introduced new violations):
+    Display: "Fix introduced {N} new blockers."
     Set next_required_action to "/sdlc:fix"
 
-  IF re-review passes (zero blockers):
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:fix in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:fix.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:fix — Review the new findings and run /sdlc:fix again."
+      Wait for user to manually run the command.
+    </auto_advance>
+
+  IF re-verify passes (zero blockers):
     Display:
     ```
-    Review PASSED after fixes: 0 blockers.
+    Verify PASSED after fixes: 0 blockers.
     Warnings: {count}
     Info: {count}
 
-    NEXT ACTION REQUIRED: /sdlc:close
-    Run /sdlc:close to close this loop.
+    NEXT: /sdlc:close
     ```
 
-  WHY: Re-review confirms the fixes are correct and complete. Without re-review, a fix that introduced a new violation would slip through to close.
+    <auto_advance>
+    Read .sdlc/STATE.md auto_advance setting.
+    IF auto_advance is true:
+      Display: "Auto-advancing to /sdlc:close in {advance_delay_seconds}s — reply to intervene."
+      Sleep for {advance_delay_seconds} seconds using Bash sleep command.
+      If no user message received during sleep: automatically execute /sdlc:close.
+      If user sends a message: cancel auto-advance, process user input, then resume.
+    IF auto_advance is false:
+      Display: "NEXT ACTION REQUIRED: /sdlc:close"
+      Wait for user to manually run the command.
+    </auto_advance>
+
+  WHY: Re-verification confirms the fixes are correct and complete. Without re-verify, a fix that introduced a new violation would slip through to close.
 </step>
 
 </process>