Unified spec.md (SPEC-630)

SPEC-630 introduced the unified spec.md format, eliminating the separate technical.md file that Planu previously required. This page explains the motivation, the new structure, and how to migrate existing specs.

Background — Why We Merged technical.md

Before SPEC-630, every spec lived in two files:

planu/specs/SPEC-NNN-my-feature/
  spec.md        ← acceptance criteria + problem statement
  technical.md   ← implementation detail, types, file lists

This caused three recurring problems:

1. Drift. Criteria in spec.md evolved but technical.md was not updated in lockstep.
2. Context waste. Loading both files consumed ~50–100 K tokens per request even for simple queries.
3. Placeholder pollution. technical.md was often a stub with double-dash separators (--) that tools could not distinguish from real content.

After SPEC-630: a single spec.md with a ## Technical section at the bottom.

The ## Technical Section

The ## Technical section follows the last acceptance criterion. It uses consistent sub-headings that Planu tools know to look for:

## Technical

### Files to create

- `src/feature/my-module.ts` — short description
- `src/feature/my-module.test.ts` — unit tests

### Files to modify

- `src/index.ts` — export the new module

### Implementation order

1. Create types/interfaces
2. Implement core logic
3. Add tests
4. Wire exports

### Key types / interfaces

​```ts
interface MyFeatureOptions {
  enabled: boolean
  timeout: number
}
​```

### Test stubs

​```ts
describe('myFeature', () => {
  it('should do X given Y', async () => {
    // TODO: implement
  })
})
​```

Sub-sections are optional

Include only the sub-sections that apply. A docs type spec may only need ### Files to create. A refactor spec may need ### Files to modify and ### Key types / interfaces.

Before / After Diff

 planu/specs/SPEC-NNN-my-feature/
-  spec.md          ← criteria only
-  technical.md     ← separate implementation file
+  spec.md          ← criteria + ## Technical section unified

Inside the file, the difference looks like:

 ## Acceptance Criteria
 
 **Scenario 1: ...**
 - GIVEN ...
 - WHEN ...
 - THEN ...
+
+## Technical
+
+### Files to create
+
+- `src/my-feature.ts` — main implementation

Migrating Existing Specs

If your project has specs with a separate technical.md, use the heal_spec_docs tool to migrate them automatically:

# Migrate a single spec
heal_spec_docs("SPEC-NNN")

# Migrate all specs in the project
heal_spec_docs("*")

What heal_spec_docs Does

heal_spec_docs applies the following heuristics:

1. Placeholder detection. If technical.md contains only double-dash separators (--) or is empty, the tool considers it a stub and deletes it.
2. Merge. If technical.md has real content, the tool appends a ## Technical section to spec.md with that content, then deletes technical.md.
3. Validation. After merging, the tool runs check_readiness to verify the unified file is coherent.

Manual review after migration

Always review the merged ## Technical section after running heal_spec_docs. Auto-merges preserve the content but may reorder sub-sections.

---

Cross-links

• Lean Spec Format — frontmatter fields that live at the top of the same file
• Auto-Status Transitions — the validate cascade that checks the unified criteria