# Skill: Technical Spec Generation

Purpose: Convert confirmed requirements into a formal technical specification.

## Steps
1. Read `specs/.spec-counter` for the next available integer ID. Zero-pad it to 3 digits (e.g. `1` -> `001`) to form `<id>`. Copy `specs/templates/spec-template.md` into `specs/active/SPEC-<id>-<short-name>.md`, then increment the value in `specs/.spec-counter` by 1 and save it, so the next spec gets a unique ID. Never reuse an ID, even if a spec is later abandoned.
2. Fill in Business Context, Acceptance Criteria, and Technical Design sections.
3. Define data model/schema changes explicitly, including dialect-specific syntax.
3a. Before finalizing **Target Files**, check every other spec currently in `specs/active/` for overlap with this list. If another active spec already lists one of the same files, flag it to the user and note the conflicting spec ID in this spec's Business Context — do not silently proceed with both specs touching the same file concurrently.
4. Define function/API contracts with explicit parameter types.
5. Break the work into an atomic implementation checklist per `.devfoundry/skills/task-decomposition.md`, pairing each implementation task with a preceding failing-test (or manual-verification, for legacy stacks) task per the TDD rule in `.devfoundry/rules/general.md`.
6. Run the Spec Readiness Checklist below.
7. Mark spec status as `DRAFT` and present to the user for approval before implementation begins.

## Spec Readiness Checklist
- Status is `DRAFT`.
- Business Context, Acceptance Criteria, Technical Design & Contracts, Implementation Plan, Verification & Regression Plan, and Target Files are complete.
- Active specs in `specs/active/` have been checked for Target Files overlap.
- Build/test/lint commands are documented in `.devfoundry/references/environments.md`, or the spec explicitly records that no command exists for the affected stack.
- If database changes are included, current schema notes, target-engine DDL, dependent queries/views/reports, and rollback or backup steps are documented.
- If no database/schema changes are included, the Data Model / Schema Changes section records exactly: `No schema changes; rollback is git revert.`
- Every implementation task has a preceding test/manual-verification task and includes space for `completed: <YYYY-MM-DD HH:MM>` timestamps.

## Abandoning a DRAFT Spec
If the user cancels a `DRAFT` spec before approval:
1. Set the spec's `Status` field to `ABANDONED`.
2. Add a brief cancellation reason in Business Context or a final note at the bottom of the spec.
3. Move it to `specs/archive/SPEC-<id>-<short-name>.md`.
4. Do not decrement `specs/.spec-counter` and do not reuse the ID.

## Amending an APPROVED or IN PROGRESS Spec
An `APPROVED` (or later) spec's Acceptance Criteria and Technical Design are frozen. If the user requests a genuine scope change (not a bug in the Builder's execution) after that point:
1. Do not edit the frozen sections in place. Append a new `## Revision <n> — <YYYY-MM-DD>` section to the bottom of the spec file describing what changed and why.
2. Update the affected Acceptance Criteria / Technical Design / Implementation Plan entries, keeping the original text visible above the revision (strike through or annotate as superseded — do not delete it).
3. Set the spec's `Status` field to `REVISED`.
4. Present the revision diff to the user for approval, the same as the original DRAFT.
5. Once approved, set `Status` back to `IN PROGRESS` (or `APPROVED` if implementation has not started yet) and continue.
6. If the change is large enough that it is effectively a new feature, decompose it into a new spec (new ID from `specs/.spec-counter`) instead of revising this one, and note the cross-reference in both files.