| name | spec |
| description | Generate a structured spec (decision table, state diagram, or EARS) from a GitHub issue. TRIGGER when starting work on a feature with combinatorial logic (role × policy × state), lifecycle state machines, or hardware-critical behavior — especially Critical or High tier modules (auth.py, federation.py, peer_auth.py, storage.py migrations, can_reader.py). DO NOT trigger for simple bug fixes, Low-tier changes, straightforward linear features, or documentation. |
/spec — Structured Feature Spec
For combinatorial / lifecycle / hardware-critical features, generate a
spec BEFORE writing tests or code. Post it as an issue comment on the
target issue, then wait for review.
/spec <issue-number> reads the issue with gh issue view, picks the
right format from the table below, and posts the spec for review.
Format selection
| Feature shape | Spec format | Telltale signs |
|---|
| Policy / permission logic | Decision table | role × state × config combine to decide allow/deny/show/hide |
| Lifecycle / workflow | State diagram (Mermaid) | named states with explicit transitions (create → activate → expire) |
| Hardware / safety-critical | EARS requirements | sensors, devices, thresholds, fail-safes, "THE SYSTEM SHALL" |
| Mixed | Combine | e.g., state diagram for the lifecycle + decision table for permissions inside each state |
If the issue is simple enough that none of the formats add value (plain
CRUD, no combinatorial logic), say so and skip the spec. Not every issue
needs one.
Decision-table cookbook
- Columns: every input variable that affects the outcome (role, state,
config flag, tier).
- Output column(s): the result for each combination.
- Every row is one test case.
- Include the exhaustive set of meaningful combinations — no implicit
"and everything else is denied". Mark impossible rows as
n/a rather
than omitting them.
State-diagram cookbook
Use Mermaid stateDiagram-v2 so it renders in GitHub:
```mermaid
stateDiagram-v2
[*] --> Available : plugin registered
Available --> Selected : user selects
Selected --> Active : analysis runs
Active --> Selected : new session loaded
```
Name every state and every transition trigger. List guard conditions
below the diagram (e.g., "Selected → Active: only if session has required
data fields").
EARS cookbook
| Pattern | Template |
|---|
| Ubiquitous | THE SYSTEM SHALL <action> |
| Event-driven | WHEN <trigger> THE SYSTEM SHALL <action> |
| State-driven | WHILE <state> THE SYSTEM SHALL <action> |
| Conditional | IF <condition> THEN THE SYSTEM SHALL <action> |
| Optional | WHERE <feature> IS SUPPORTED THE SYSTEM SHALL <action> |
One requirement per line; each independently testable. Use measurable
conditions (thresholds, timeouts, counts), not vague qualifiers
("quickly", "reliably"). Include fail-safe requirements (what happens
when inputs are missing or stale).
Posting and approval
gh issue comment <number> --body "$(cat <<'EOF'
## Structured Spec
**Risk tier:** <tier>
**Spec format:** <format>
<spec content>
---
*Generated by /spec. Review and approve before implementation begins.
Each row in a decision table = one test case. Each state transition = one
test case.*
EOF
)"
Do not proceed to TDD until the spec is approved. If the user
requests changes, update the comment and re-request review.
For features touching federation or data licensing, also read
docs/federation-design.md and docs/data-licensing.md so the spec is
consistent with existing policy. If the issue was promoted from an IDX
entry, cross-reference the ideation log for design decisions and open
questions.
