Add Post-Implementation Debugging and Fixing Workflow

[RotRot-pi]

Problem Statement

The current Spec-Driven Development workflow provides excellent structure for initial development (constitution → specify → plan → tasks → implement), but lacks a systematic approach for handling broken or incomplete implementations that result from the /implement command.

Current Gap

What happens now:

1. /implement executes the planned tasks
2. Code is generated but may contain runtime errors, logic bugs, or missing functionality
3. Developer is left to manually debug and fix issues outside the Spec Kit framework
4. No structured way to ensure fixes align with original specifications

Real-world scenarios:

Scenario 1: Build Failures

• AI agent generates Flutter app code following the implementation plan
• Code contains syntax errors, missing imports, or incorrect API usage
• flutter build or dart analyze fails with compilation errors
• Developer must manually identify and fix code issues outside the Spec Kit framework

Scenario 2: Runtime Issues

• AI agent successfully generates Flutter app structure that compiles
• App builds but crashes on startup due to missing dependencies or configuration
• Runtime errors appear in device logs or debug console during testing
• Logic bugs surface during user testing that weren't caught in generation
• No clear path to systematically address these issues within the Spec Kit methodology

Proposed Solution

Add a post-implementation workflow to handle debugging and fixes while maintaining spec-driven principles:

Option 1: Dedicated Fix Commands

/diagnose    # Analyze errors, identify root causes, check spec alignment
/fix         # Implement targeted fixes based on diagnosis

Option 2: Enhanced Iteration Command

/iterate     # Fix issues and improve implementation while maintaining spec compliance

Option 3: Robust Implementation

Enhance /implement to include error handling, validation, and retry logic for common failure scenarios.

Why This Aligns with Spec-Driven Development

1. Iterative Enhancement Phase: The mention of "Iterative Enhancement (Brownfield)" as a supported development phase
2. Specification Integrity: Bugs often reveal gaps in original specs - fixes should update both code AND specifications
3. Complete Development Lifecycle: Real software development includes debugging, not just initial creation
4. Enterprise Readiness: Mission-critical applications need robust error handling and fixing workflows

Expected Behavior

A /fix or similar command should:

• Analyze current codebase against specifications
• Identify discrepancies between expected and actual behavior
• Generate targeted fixes that maintain spec compliance
• Update relevant specification documents if gaps are discovered
• Preserve the structured, traceable development approach

Use Case Example

# After /implement generates broken code
/diagnose "App crashes on startup with SQLite connection error"

# Command would:
# 1. Analyze error logs
# 2. Check against database setup in plan.md
# 3. Identify missing configuration or dependencies
# 4. Suggest specific fixes

/fix
# Execute the identified fixes while maintaining spec alignment

Benefits

• Maintains Spec-Driven Approach: Fixes are systematic, not ad-hoc
• Improves Success Rate: Higher likelihood of working implementations
• Enterprise Viability: Addresses real-world development cycles
• Specification Evolution: Allows specs to improve based on implementation learnings

Impact on Current Workflow

This would extend the existing workflow from:
constitution → specify → plan → tasks → implement

To:
constitution → specify → plan → tasks → implement → [diagnose/fix as needed]

The addition is backwards-compatible and optional - projects with successful implementations wouldn't need the debugging workflow.

---

Environment:

• Using Spec Kit with Flutter desktop application development
• Observed this gap during real project implementation
• AI Agent: Qwen Code

Related:
This enhancement would support the "Iterative Enhancement" and "Enterprise constraints" experimental goals.

[nitish-raj]

+1 This is definitely required.

[localden]

@RotRot-pi - what is the delta between /diagnose and /fix? Seems somewhat redundant. I also think this should likely be better integrated either into one command or, if split, potentially rely on /implement in some capacity to prevent command sprawl.

[RotRot-pi]

@localden Thanks for replying.
My original thought was like this:

-/diagnose = analyze and identify issues
-/fix = actually implement the fixes

It felt necessary to have two separate commands. One to identify the issues and plan for a fix while the other to implement the plan. Since you have mentioned it, I understand that it can feel redundant.

We already have a powerful /implement command, and we can treat the bugs/errors as another kind of tasks.
We can use /diagnose command to analyze the error, logs, and project context and run some validation scripts (flutter analyze) to gather more data.

Then it will create a new set of tasks using the same tasks.md format. We can then use the /implement command to work on these new tasks.

We can have a new section in the generated tasks dedicated for the tasks related to fixing issues, or we can have a separate file in the same format of tasks.md where we have the issues as tasks. Then using a new flag /implement --fix "path/to/file" we implement the necessary fixes.

[joesh]

I'm new to spec kit and am loving it. I'm also at exactly this stage of things, having spec'ed a very substantial project and had great success so far with spec kit guiding it after a fairly miserable experience of letting Claude Code tackle what I thought was a sufficiently well thought out spec.

I'd be happy to be a guinea pig for this new facility or help in whatever other way might be useful. Cheers!

[onarres]

+1 - I've only been working with spec-kit for a few days; I always find more details/fixes/tweaks needed after implementation and we are left with starting over going to a previous commit and rerun the clarify all the way to implement, but that is not ideal because you already spent so many tokens on the first implementation. I have been trying to /clarify without backing out the current state, but it gets confused quickly.

I am definitely eager for features like the /fix /iterate /update-spec etc.

[ebramirez]

Somewhat related to #549

[grayson1999]

나도 필요하다고 느낀다. +1

[Kataki-Takanashi]

@RotRot-pi - what is the delta between /diagnose and /fix? Seems somewhat redundant. I also think this should likely be better integrated either into one command or, if split, potentially rely on /implement in some capacity to prevent command sprawl.

I agree with this direction, and I think it also lines up really well with how Spec Kit already handles planning and gives the user an opportunity to look at the plan.

A “fix” can’t really happen without diagnosing first, and Spec Kit already has a pattern where nothing changes until there’s a plan the user can review. So if /fix existed, it would still need to analyze the error, propose tasks, and let the user correct assumptions before touching code, which starts to look a lot like /implement.

Because of that, it feels cleaner if /diagnose just generates fix tasks (maybe in the tasks.md file or a debug.md) that capture what failed, what was already tried, and any user corrections. Then you just run/implement (or /implement --fix) on those tasks.

One thing this would help with is avoiding the agent from retrying the same bad assumptions during debugging. If prior attempts and corrections are written down explicitly, its less likely to forget and loop.

That keeps debugging consistent with the existing workflow and avoids adding commands that overlap too much. But that's just my two cents from a mostly outside perspective.