# SpecKit Learning Path Strategy

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

TraderX uses a convergence-first state model on top of GitHub Spec Kit artifacts in `specs/` and `.specify/`.

## Canonical Progression

*   Prelude onboarding: `001 -> 002`
*   `C0`: `003`
*   Architecture to `C1`: `004 -> 005 -> 006`
*   Functional to `C2`: `007 -> 008`
*   Platform to `C3`: `009 -> 010 -> 011`
*   Optional side branch: `012` off `009`

Convergence checkpoints:

*   `C0`: `004-containerized-compose-runtime`
*   `C1`: `007-observability-lgtm-compose`
*   `C2`: `009-order-management-matcher`
*   `C3`: `012-platform-convergence-c3`

## Lineage Rules

*   `previous` is the single publish lineage parent (max length 1).
*   `dottedParents` is documentation lineage only and allowed only on convergence states.
*   `primaryLineageRole` is one of `prelude`, `canonical`, `optional`.

## Authoring Guidance

1.  Start new work from the nearest suitable convergence state by default.
2.  Create one feature pack per transition.
3.  Add FR deltas only when behavior changes.
4.  Add NFR deltas for runtime/platform/ops objectives.
5.  Keep contract changes scoped and explicit.
6.  If changing a convergence state, update `system/convergence-rationale.md`.

## Required Artifacts Per Transition

*   `spec.md`
*   `plan.md`
*   `tasks.md`
*   `system/**` (requirements, flows, architecture, topology)
*   `generation/generation-hook.md`
*   `generation/patches/*.patch` for derived-state implementation deltas
*   `tests/smoke/README.md`

## Validation and Promotion Loop

1.  Update spec artifacts.
2.  Regenerate state outputs.
3.  Refresh catalog-derived docs.
4.  Run gates and state smoke tests.
5.  Publish generated code branch when green.

Commands:

```bash
bash pipeline/refresh-state-docs.shbash pipeline/verify-spec-coverage.shbash pipeline/publish-generated-state-branch.sh <state-id> --push
```

## References

*   State catalog: `catalog/state-catalog.json`
*   Visual graph: `/docs/learning-paths`
*   Convergence policy: `/docs/spec-kit/convergence-states`