Spec

---
name: ba-spec
description: Write the six spec entities — FR, NFR, UC, US, AC, TC — each strictly derived from the kind above it in the chain, then compose them into the two signed deliverables PRD-001.md and SRS-001.md. Use when a project has EPICs but no FRs yet, before writing a UC/US/AC/TC, or before /ck:tickets needs a signed SRS.
license: MIT
---

# Spec

The centre of the kit. Six entity-writing actions plus `compose`, which renders the signed
deliverable. Everything upstream (`plan`, `prd`) exists to produce the EPICs this skill consumes;
everything downstream (`/ck:tickets`, phase 08) consumes what `compose` writes.

## The derivation chain — this ordering IS the methodology

```
EPIC-001 ──> FR-012 ──> UC-004        (how the actor does it)
                    └─> US-007 ──> AC-007.1 ──> TC-021
             NFR-003 (parents PRD-001 or an EPIC)
```

One action per kind, and each derives from the kind above it. Without this ordering the kit is a
template pile — a spec written from imagination, not from the product decisions already on record.

## The eight actions

| action | derives from | writes |
|---|---|---|
| `fr` | `EPIC-*` | `FR-###.md` |
| `nfr` | `PRD-001` or `EPIC-*` | `NFR-###.md` |
| `uc` | `FR-*` | `UC-###.md` |
| `us` | `EPIC-*`, `FR-*`, or `UC-*` | `US-###.md` |
| `ac` | `US-*` or `FR-*` | `AC-###.#.md` |
| `tc` | `AC-*`, `FR-*`, or `NFR-*` | `TC-###.md` |
| `cr` | an existing entity (EPIC/FR/NFR/UC/US) | `CR-###.md` |
| `compose` | the whole index | `deliverables/{PRD-001,SRS-001}.md` |

**CR derives from an existing entity and never creates one.** A change with no entity to point at is not a change request, it is a new requirement — run `fr`.

## Refuse out-of-order generation

A `us` run against a project with no `FR-*` entities is a spec written from imagination, not
derived from a decision anyone made. **Refuse, and say which action to run first** (`fr`, off the
EPIC it should derive from). Same refusal for `uc`/`ac`/`tc` run before their parent kind exists.

## Business Process Definition

The `bp` action writes one narrative document per process, eight sections per `references/bp-structure.md`:
narrative, roles/actors, trigger, inputs/outputs, steps, business rules (as `FR-###` citations only,
never new prose), exceptions, and diagram. Class `owned` — seeded once, then hand-edited. Refuses
to overwrite an existing file. **No new kind** — BP is a document action, not a spine entity;
citations in steps are checked against the index, and business rules **must** be validated against
existing FRs to prevent duplicate sources of truth. Anti-patterns: prose rule without an FR, or
`## Sơ đồ` with neither a fence nor `[UNRENDERED]`.

## `tc` derives from AC and nothing else, and reuses rather than rewrites

D-10 folded the `test` dispatcher into this action. Rather than carrying a scenario-design method
here, **read the `scenario` skill file**
([.claude/skills/software/scenario/SKILL.md](../../software/scenario/SKILL.md)) —
§ Design Process (`:39`) and § Scenario Template (`:48`). That skill already covers happy / error /
edge / recovery paths (§ Scenario Types, `:26`) and the layer→tool mapping (§ Tool Mapping, `:62`).
This skill contributes exactly one thing on top: **every TC's `parents` names the `AC` it
exercises**, which is what makes coverage queryable by the traceability index. That is also why
`scenario/SKILL.md` is a `requires.shared` entry in `ba.json` (phase 01) instead of a copy living
here — it is link-clean, so it travels alone into a `ba`-only install.

## Rule 1 and rule 2, at the point of generation

An FR (or any entity) with no real `source:` ships the literal `[UNVERIFIED]` and
`confidence: low` — never a plausible-looking citation. This is where a hallucinated requirement
would enter the spine (R1), and the only defence is that the template has nowhere to put an
unsourced claim quietly: every rendered block carries `**source:**`/`**confidence:**`, so a skipped
citation is visible, not silently dropped.

## AC numbering

`AC-###.#` inherits its parent's three-digit number; `traceability.cjs validate` enforces the
match (`ac-prefix-mismatch`) — this skill only states the allocation rule: **assign the AC id when
its parent (`US-###` or `FR-###`) already exists, never before.** An AC numbered ahead of its
parent is a coin-flip that happens to validate today and breaks the next time a sibling FR is
inserted.

## Anti-patterns (auto-reject)

- An FR that is three FRs wearing one id — split it before writing children under it.
- An AC that is not pass/fail (a paragraph instead of Given/When/Then).
- A UC with no `Precondition:` — a use case with no starting state is a fragment, not a spec.
- A TC that restates its AC in different words instead of exercising it (no steps, no data).
- Editing `deliverables/SRS-001.md` (or `PRD-001.md`) by hand — it is regenerated by `compose`, so
  a hand-edit is lost on the next run, **and** the file is committed (D-11), so the loss lands in
  git history looking like an intentional revert of a signed document.

## Reading order

- `references/entity-bodies.md` — one worked body per kind (FR/NFR/UC/US/AC/TC), Vietnamese prose,
  English keywords.
- `references/compose-format.md` — D-4's exact rendered block, binding on `compose`'s output.

## Cross-references

- **Read the `ba-traceability` skill file** ([.claude/skills/ba/traceability/SKILL.md](../traceability/SKILL.md)) — the id scheme, entity contract, and `validate`/`index` CLI this skill's actions call before and after writing.
- **Read the `scenario` skill file** ([.claude/skills/software/scenario/SKILL.md](../../software/scenario/SKILL.md)) — the design method `tc` reuses instead of restating.
- **Read the `business-analysis-rules` workflow** ([.claude/workflows/business-analysis-rules.md](../../../workflows/business-analysis-rules.md)) — rule 1 (sourcing), rule 2 (confidence), rule 6 (hard-fail pre-flight), rule 7 (output language), rule 8 (storage; do-not-hand-edit a committed deliverable).