---
name: tracked-story
description: "Use when delivering a business story with traceability: analyze and get acceptance, implement, review, reconcile the README, then commit locally with a gate-backed evidence report."
---

# Tracked story

The SDLC policy (`policy/universal.md` in the repository) owns authority, commit and evidence rules; this skill orders the work and names the artifact each handoff produces. One story, or one independently deliverable subtask, per workflow. `copilot-sdlc` is the shared, host-neutral CLI despite its name; run it through `python scripts/sdlc.py` in this repository or by absolute path elsewhere.

Record each handoff as it closes. `commit-ready` refuses while a gate it needs is missing or stale, so a gate recorded late is a claim without evidence. A gate is fresh only for the commit it postdates: `analysis` is story-level, while `implementation`, `customization`, `review` and `docs` must be re-recorded after each commit. `implementation` and `customization` also bind to the staged tree, so stage the reviewed files before recording them.

1. **Analysis and acceptance** (`analysis`). Write the intent, acceptance criteria, assumptions, out-of-scope and risks into the story or an `analysis.md` beside it. Ask the user to accept them, then record the gate with that artifact and the approver. No implementation before acceptance unless the user explicitly accepts the risk of starting without it.

2. **Implementation** (`implementation`). Implement the narrowest change, run focused validation, then report what ran and what did not. Stage only reviewed files, then record the gate with the validation evidence, the approver and the recording host (`--run-verify` runs `scripts/verify.py` first and stores its exit code, test count and result); it binds to that staged tree. When the staged paths touch a customization layer, record `customization` at this point too (step 4 lists the layers), because the commit refuses without it. Run `commit-ready` with an `ai commit by <ai>: ` title (`<ai>` is claude, deepseek, codex or copilot); it writes the handoff report.

3. **Review** (`review`). Prefer a fresh reviewer session. Save findings, dispositions and residual risk under the story's `reviews/`, bounded to three rounds. Record the gate with that review file, then commit fixes with an `ai code review by <ai>: ` title. If nothing actionable remains, record the verdict and stop.

4. **Customization** (`customization`). Required when the change touches `policy/`, `skills/`, `core/`, `scripts/`, the root launchers or any `*-customization/` folder: name the layer that changed, run `python scripts/sync-customizations.py` and `python scripts/verify.py`, stage the reviewed files, then record the gate with the drift-check result.

5. **Documentation** (`docs`). Reconcile the end-user README with current operation, architecture and limits, then record the gate with the README path. This closes the story before publication.

6. **Handoff.** Publication is the user's operation: never push. End with outcome, changes, evidence and limits, and use `DONE`, `BLOCKED_NEEDS_USER`, `FAILED`, `STUCK`, `LIMIT_REACHED` or `SECURITY_STOP` accurately.

```powershell
python scripts/sdlc.py gate --story SDLC-001 --gate analysis --artifact .sdlc/analysis.md --evidence "Criteria accepted in chat" --approved-by "<user>" --recorded-by <ai>
python scripts/sdlc.py commit-ready --workspace . --message "<summary>" --ai-name <ai> --prepared-by <ai> --summary "<reviewed change>" --validation-summary "<checks run>" --co-author "<Name> <noreply@host.example>"
```