Custom agent imported from izkizk8/spot (.github/agents/speckit.fix-findings.run.agent.md). Copyright stays with the author.

Fix Findings

Automated analyze-fix-reanalyze loop. Runs /speckit.analyze, reads findings from analysis.md, applies fixes to implementation code, and re-analyzes until all actionable issues are resolved.

User Input

$ARGUMENTS

If arguments are provided, treat them as constraints for the fix process (e.g., "only fix critical issues", "skip style findings", "max 3 iterations").

Process

Step 1: Initialize Context

Run the check-prerequisites script from repo root to determine feature paths:

# Bash
result=$(.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks)

# PowerShell
$result = .specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks

Parse JSON output to get FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md
• ANALYSIS = FEATURE_DIR/analysis.md
• FINDINGS_LOG = FEATURE_DIR/findings.fixed.md

Abort with an error if SPEC, PLAN, or TASKS are missing. Instruct the user to run the prerequisite commands first.

Step 2: Initial Analysis

Check if analysis already exists:

• If ANALYSIS does not exist, run /speckit.analyze to generate the analysis report. Save the full Markdown output to ANALYSIS (FEATURE_DIR/analysis.md).
• If ANALYSIS already exists, read it and proceed to Step 3.

Note: /speckit.analyze outputs a Markdown report to the conversation. This extension must capture that output and persist it to ANALYSIS so it can be parsed and tracked across iterations.

Step 3: Parse Findings

Read ANALYSIS and extract all findings. A finding is any issue, inconsistency, gap, or recommendation identified by the analysis.

Categorize each finding by severity:

• Critical: Spec violations, missing implementations, broken contracts
• Warning: Inconsistencies, partial implementations, drift from spec
• Info: Style suggestions, minor improvements, documentation gaps

Count the total actionable findings (Critical + Warning). If zero, skip to Step 6.

Step 4: Apply Fixes

For each actionable finding, prioritized by severity (Critical first, then Warning):

1. Read the finding description and the affected file(s)
2. Read the relevant section of SPEC and PLAN to understand the intended behavior
3. Apply the fix to the implementation code
4. Record what was fixed

Constraints — these are non-negotiable:

• All fixes MUST align with spec.md and plan.md — never contradict the spec
• If a finding is ambiguous or requires a design decision, skip it and mark as "deferred — requires human decision"
• Do NOT modify spec artifacts (spec.md, plan.md, tasks.md) — only fix implementation code
• If the constitution exists (.specify/memory/constitution.md), all fixes must comply with its principles

Step 5: Re-analyze and Loop

After applying all possible fixes in an iteration:

1. Delete the existing ANALYSIS file
2. Run /speckit.analyze to generate a fresh analysis and save the output to ANALYSIS
3. Parse the new findings (repeat Step 3)
4. If actionable findings remain AND at least one new fix was applied, repeat Step 4
5. Stop when any of these conditions are met:
   • Zero actionable findings remain → status: CLEAN
   • No new fixes were applied in this iteration (all remaining are deferred) → status: DEFERRED_REMAINING
   • Maximum of 5 iterations reached → status: MAX_ITERATIONS_REACHED

Step 6: Generate Findings Log

Create or update FINDINGS_LOG with a complete audit trail:

# Findings Fixed Log

> Auto-generated by /speckit.fix-findings.run on {YYYY-MM-DD}

## Summary

- **Total iterations**: {N}
- **Findings resolved**: {RESOLVED_COUNT}
- **Findings deferred**: {DEFERRED_COUNT}
- **Final status**: {CLEAN | DEFERRED_REMAINING | MAX_ITERATIONS_REACHED}

## Iteration 1

### Findings Identified
- [Critical] {description} — {file}:{line}
- [Warning] {description} — {file}:{line}

### Fixes Applied
- Fixed {description} in `{file}` — {what changed}

### Findings Deferred
- [Warning] {description} — Reason: {why deferred}

## Iteration 2
...

Step 7: Report Results

Print a summary:

Fix Findings Complete
====================
Iterations:  {N}
Resolved:    {RESOLVED_COUNT} findings
Deferred:    {DEFERRED_COUNT} findings
Status:      {FINAL_STATUS}

Log saved to: {FEATURE_DIR}/findings.fixed.md

If any findings were deferred, list them so the user can address them manually.

Output Files

Notes

• This command is non-destructive to spec artifacts — it only modifies implementation code
• The 5-iteration safety limit prevents infinite loops
• Deferred findings require human judgment and are logged for follow-up
• Re-running the command after addressing deferred items will pick up where it left off
• Constitution principles (if present) are treated as non-negotiable constraints