How to fix code after doing speckit.implement agent? (Ask Best Practice)

[anggaaryas]

Any best practice how do you fix the code after running speckit.implement agents? I tried to fix the code as usual, but i think i need to create custom instruction to make the agent look to spec folder. Maybe we need another speckit agent? like speckit.fix maybe?

[mykolaveremeichyk]

Hi. I'm using the /clarify command to make modifications within the scope of the same specification.
It makes updates to the spec.md, asks the questions if needed, and then I do /plan, /tasks, and /implement.

[anggaaryas]

Hi. I'm using the /clarify command to make modifications within the scope of the same specification.
It makes updates to the spec.md, asks the questions if needed, and then I do /plan, /tasks, and /implement.

Does it fix the code and not making 002 spec? The spec is already ok. But the implementation sometimes makes error.

[anggaaryas]

Hi. I'm using the /clarify command to make modifications within the scope of the same specification.
It makes updates to the spec.md, asks the questions if needed, and then I do /plan, /tasks, and /implement.

Does it fix the code and not making 002 spec? The spec is already ok. But the implementation sometimes makes error.

[sl40168]

I'm using /speckit.implement command, @Specified code file, even the lines of snippet, then clarify the issue and asked it to fix. Usually, it will review existing spec/plan or some other related document automatically and fix it. Hope it also work for you.

[mykolaveremeichyk]

Hi. I'm using the /clarify command to make modifications within the scope of the same specification.
It makes updates to the spec.md, asks the questions if needed, and then I do /plan, /tasks, and /implement.

Does it fix the code and not making 002 spec? The spec is already ok. But the implementation sometimes makes error.

It doesn't make a new spec, just applies updates to the spec.md. I noticed one time that it did the upodates right to the code with proposal to run plan, tasks and implement to make them consistent.
Sometime this command activates clarification questions from llm.

[anggaaryas]

using implement and clarify agents sometimes did not follow my request. Now i am experimenting with speckit.fix.agent.md using Claude Sonnet 4.5

speckit.fix.agent.md

---

description: Diagnose and fix issues in an existing project by analyzing implementation against spec materials without modifying specifications.
handoffs:

• label: Analyze For Consistency
  agent: speckit.analyze
  prompt: Run a project analysis for consistency
  send: true
• label: Generate Tasks
  agent: speckit.tasks
  prompt: Generate tasks from the spec
  send: true

---

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

Goal: Diagnose issues in an existing project implementation by comparing against spec materials, then generate targeted fixes. This agent does NOT modify specification files—only implementation code.

1. Setup: Run .specify/scripts/bash/check-prerequisites.sh --json from repo root and parse JSON payload fields:

   • FEATURE_DIR - Directory containing spec materials
   • FEATURE_SPEC - Path to spec.md
   • IMPL_PLAN - Path to plan.md
   • TASKS - Path to tasks.md
   • AVAILABLE_DOCS - List of available documentation
   • For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
   • If JSON parsing fails, abort and instruct user to verify feature branch environment.

2. Load Spec Materials (Read-Only): Load the following files for reference only—do NOT modify them:

   • spec.md: User stories, functional requirements, success criteria
   • plan.md: Tech stack, project structure, implementation approach
   • tasks.md: Task breakdown and completion status
   • data-model.md: Entity definitions (if exists)
   • contracts/: API contracts (if exists)

3. Issue Discovery: Based on user input, determine the fix scope:

   a. If user describes a specific issue:

   • Parse the issue description from $ARGUMENTS
   • Identify affected components (files, modules, endpoints)
   • Map issue to relevant spec sections for context

   b. If user requests general diagnostics (no specific issue):

   • Scan implementation files against spec requirements
   • Check for common issue patterns (see Diagnostic Patterns below)
   • Identify discrepancies between spec and implementation

   c. If user points to error output/logs:

   • Parse error messages and stack traces
   • Identify root cause location in codebase
   • Cross-reference with spec for expected behavior

4. Diagnostic Analysis: For each identified issue, perform:

   Analysis Type	Action
   Spec Alignment	Compare implementation against spec.md requirements
   Contract Compliance	Verify endpoints match contracts/ definitions
   Data Model Consistency	Check entities match data-model.md schema
   Task Completion	Verify task implementation matches tasks.md description
   Error Pattern	Identify common coding errors (null handling, type mismatches, etc.)

5. Generate Fix Report: Create a structured diagnosis:

   ## Issue Diagnosis
   
   **Issue**: [Brief description]
   **Severity**: [Critical / High / Medium / Low]
   **Affected Files**: [List of files]
   
   ### Root Cause
   [Explanation of why the issue occurs]
   
   ### Spec Reference
   [Quote relevant spec.md section showing expected behavior]
   
   ### Current Implementation
   [Quote or describe current (incorrect) implementation]
   
   ### Proposed Fix
   [Describe the fix approach]

6. Apply Fixes: Based on diagnosis, apply targeted code fixes:

   a. Before fixing:

   • Confirm fix scope with user if changes affect multiple files
   • For breaking changes, warn user and request confirmation

   b. Fix execution:

   • Apply minimal, focused changes to resolve the issue
   • Preserve existing code style and conventions
   • Add appropriate error handling if missing
   • Update related tests if they exist

   c. After fixing:

   • Run linters/formatters if available (e.g., dart fix, dart format)
   • Run tests if available to verify fix
   • Report changes made with file paths and descriptions

7. Validation: After applying fixes:

   • Verify fix addresses the original issue
   • Check for regressions in related functionality
   • Confirm implementation still aligns with spec requirements
   • Run project-specific validation commands if defined in plan.md

8. Report Completion: Output summary:

   • Issues diagnosed and fixed
   • Files modified (with line counts)
   • Tests run and results
   • Any remaining issues requiring manual attention
   • Suggested follow-up actions

Diagnostic Patterns

Common issue patterns to check during general diagnostics:

Code Quality Issues

• Missing null/empty checks
• Unhandled error cases
• Type mismatches or incorrect casts
• Memory leaks or resource cleanup
• Race conditions in async code

Spec Compliance Issues

• Missing required fields from data model
• Incorrect API response formats vs contracts
• Missing validation per functional requirements
• Incomplete user story implementation
• Missing edge case handling

Integration Issues

• Incorrect endpoint URLs or methods
• Missing authentication/authorization checks
• Incorrect request/response serialization
• Missing error propagation

Test Issues

• Tests not covering spec requirements
• Flaky or non-deterministic tests
• Missing edge case tests
• Outdated test expectations

Fix Rules

CRITICAL: This agent must NEVER modify specification files.

What This Agent CAN Modify

• Implementation source code (lib/, src/, app/, etc.)
• Test files
• Configuration files (if fix-related)
• Build scripts (if fix-related)

What This Agent CANNOT Modify

• spec.md
• plan.md
• tasks.md
• data-model.md
• Any file in contracts/
• Any file in checklists/
• research.md
• quickstart.md

Fix Principles

1. Minimal changes: Only modify what's necessary to fix the issue
2. Spec-aligned: Fixes must align with spec requirements, not change them
3. Tested: Run available tests after fixes when possible
4. Documented: Explain each change in the completion report
5. Reversible: Prefer fixes that can be easily reverted if needed

When to Escalate

If fixing an issue requires changing the specification (e.g., spec contains a contradiction or impossible requirement):

1. Do NOT modify the spec
2. Document the spec issue clearly
3. Recommend running /speckit.clarify to address the spec issue
4. Apply temporary workaround if safe, clearly marked with TODO comment

Context for Diagnosis

Context from user: $ARGUMENTS