incremental-implementation

Incremental Implementation

Overview

Implement in thin slices. Each slice must compile, test, and remain explainable before moving on. Use test-driven-development for the test strategy inside each slice and source-driven-development when framework behavior is uncertain.

When To Use

• Any approved multi-file implementation
• Refactors that still require verification
• Any task where the cost of late failure is high

When NOT To Use

• Single-file, single-function changes already minimal enough for the fix workflow

Workflow

1. Before each batch, re-read the relevant rules from CLAUDE.md and the shared references.
2. Ask the simplicity question: what is the smallest correct implementation that could work?
3. Implement only the files listed for the batch.
4. Follow test-driven-development for tests in the same batch.
5. Use source-driven-development when any framework, library, or SDK behavior is uncertain.
6. Run the batch checkpoint using the build and test commands from the active tech stack skill's ## Build & Test Commands. 6.5. Capture analyzer output. After the build command completes, pipe its output through the build diagnostics parser if available:

   # Example for .NET (adapt command from tech stack skill's Build & Test Commands):
   dotnet build 2>&1 | tee /dev/tty | hooks/parse-build-diagnostics.sh > .mtk/analyzer-output.json
   

   Surface any critical analyzer findings immediately — they block the batch just like build failures. Warning-level findings carry forward to the pre-commit review. If hooks/parse-build-diagnostics.sh does not exist in the installed toolkit, skip this step.
7. Read .claude/references/pre-commit-review-list.md if present and fix any violations immediately.
8. Mark the batch complete in tasks/todo.md. Record the per-batch gate decision on the workflow artifact: scripts/workflow-artifact.sh gate "$MTK_WF_UUID" phase_exit_gate pass --reason "batch <id> green" (or fail to trigger remediation). See .claude/references/orchestration-gates.md.
9. Churn check: After completing each batch, run git diff --stat and count net lines changed. If cumulative changes across batches exceed 300 lines, pause and trigger an early review checkpoint:
   • Run the pre-commit review list if present
   • Assess whether the scope is still within the approved manifest
   • If changes exceed 500 lines without a review, stop and run compliance-reviewer before continuing
   • This catches large unplanned changes mid-implementation rather than at the end
10. After all batches, run the full test command from the tech stack and write an explicit behavioral diff.
11. Append the implement section to the JSON handoff artifact at docs/specs/<date>-<slug>.json. Schema: .claude/schemas/handoff.schema.json. Required keys:

    "implement": {
      "actual_files": ["..."],         // git diff --name-only <base>...HEAD
      "completed_batches": ["B1","B2"],
      "deviations": [
        { "kind": "extra-file", "detail": "src/Helper.cs",
          "justification": "needed to unblock B2; spec did not anticipate" }
      ],
      "behavioral_diff": "..."
    }
    

    Be honest about deviations — spec-drift-detection will diff change_manifest against actual_files regardless. Run bash scripts/validate-handoff.sh docs/specs/<date>-<slug>.json to surface drift before handing off to review.