[Feature]: /speckit:fix-findings

[ondrovic]

Problem Statement

After running /speckit:analyze, resolving all identified issues typically involves repeating the fix and re-analysis process multiple times.

Proposed Solution

Implement a new command /speckit:fix-findings that iteratively analyzes and resolves findings until no issues remain, while documenting progress.

✅ Tasks

• Command Creation

  • Add new command /speckit:fix-findings
  • Ensure command is discoverable and callable like existing commands

---

• Analysis Integration

  • Invoke :analyze as the first step if an existing specs/analysis.md doesn't already exist, if it does skip this step
  • Persist analysis output to specs/analysis.md
  • Note: If persistence is not currently supported, create a separate task/PR to enable saving findings

---

• Fix Loop Implementation

  • Read from specs/analysis.md
  • Apply fixes for all identified issues
  • Re-run :analyze
  • Update specs/analysis.md with latest results
  • Repeat loop until no issues are detected

---

• Findings Log Output

  • Create file specs/findings.fixed.md if it does not exist

  • Append details for each iteration:

    • Issues identified
    • Fixes applied
    • Result after re-analysis

  • Ensure entries are chronological and clearly separated per loop

---

• Documentation

  • Document /speckit:fix-findings command usage

  • Include:

    • Purpose
    • Example workflow
    • Expected outputs (analysis.md, findings.fixed.md)

  • Add notes about iterative fixing behavior

---

• Agent Compatibility

  • Ensure command works across all supported agents
  • Validate no agent-specific assumptions break execution

---

Alternatives Considered

Manual process

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

All agents

Use Cases

Here are some solid, non-fluffy use cases you can drop into your issue:

---

📌 Use Cases

• Iterative Issue Resolution

  • A user runs /speckit:analyze and receives multiple findings
  • Fixing one set of issues may surface additional findings
  • The user must repeatedly re-run analysis until all issues are resolved

---

• Reducing Manual Workflow Overhead

  • Users currently need to manually:

    • Run analysis
    • Apply fixes
    • Re-run analysis

  • This process is repetitive and time-consuming

---

• Ensuring Complete Resolution

  • Users want confidence that all findings are addressed
  • Manual iteration increases the risk of missing or skipping issues

---

• Standardizing Fix Process Across Agents

  • Different agents may resolve issues differently
  • A structured loop ensures consistent behavior and outcomes

---

• Auditability / Change Tracking

  • Teams want a clear record of:

    • What issues were found
    • What fixes were applied
    • How many iterations were required

  • Useful for debugging, reviews, and continuous improvement

Acceptance Criteria

🎯 Success Criteria

• Running /speckit:fix-findings triggers a full analyze → fix → re-analyze loop
• Loop continues automatically until zero findings remain
• specs/analysis.md is created and/or updated on each iteration
• specs/findings.fixed.md logs each pass with meaningful details
• No manual intervention required between iterations
• Works consistently across all agents
• Documentation is complete and clear

Additional Context

⚠️ Out of Scope (Optional Follow-up)

• Persisting :analyze results (if not already supported) should be handled in a separate task/PR