104 lines
6.4 KiB
Markdown
104 lines
6.4 KiB
Markdown
# spec and ticket layer
|
||
|
||
_Status: settled — grilled 2026-07-17 (open questions resolved)_
|
||
_Connects to: [pipeline-stages](pipeline-stages.md), [worktree-parallelism](worktree-parallelism.md), [never-ask-twice](never-ask-twice.md), [overview](../OVERVIEW.md)_
|
||
|
||
## Purpose
|
||
|
||
States where specs and tickets live and how a plan becomes an increment `/implement` can
|
||
consume. Load this before designing `to-spec`, `to-tickets`, or any skill that reads/writes
|
||
issue-tracker state for os-sdlc.
|
||
|
||
## Design
|
||
|
||
- **Git issues are the durable spec layer.** Forgejo (via `tea`) or GitHub (via `gh`),
|
||
resolved per-project by the os-backlog tracker key in `.cc-os/config`
|
||
(`forgejo:owner/repo`, `github:owner/repo`, or `repo:path` — ADR-0042). Planka is retired;
|
||
there is no separate os-sdlc storage for specs or tickets.
|
||
- **Composability constraint (ADR-0037):** os-sdlc consumes `os-backlog` rather than
|
||
reinventing ticketing. Ticket intake, creation, and listing go through os-backlog's
|
||
`issue-create`/`issues` CLI wrappers, not a parallel os-sdlc data model.
|
||
- **Pocock lifecycle mapping**, adapted to the git-issues substrate:
|
||
- **wayfinder** — big plans, new ideas. Free-form exploration, not yet tracker-shaped.
|
||
- **grill-with-docs** — sharpens or decomposes a plan further where user direction is
|
||
genuinely needed (see [never-ask-twice](never-ask-twice.md) for when a question should
|
||
instead be answered by lookup rather than posed here).
|
||
- **to-spec** — publishes the sharpened plan to the issue tracker as a spec-bearing issue
|
||
(or epic-equivalent) — the durable artifact other stages read from.
|
||
- **to-tickets** — decomposes the spec into feature-specific, independently-implementable
|
||
increments, each its own issue, tracer-bullet style. Confirmed 2026-07-16: this is
|
||
Pocock's v1.1 *rename* of `to-issues` ("a spec defines the destination; tickets are the
|
||
journey"), not a sibling — the leftover `to-issues` skill was removed the same day.
|
||
- **`/implement`** — consumes exactly one ticket into the [pipeline-stages](pipeline-stages.md)
|
||
pipeline. One ticket in, one worktree/branch out (see
|
||
[worktree-parallelism](worktree-parallelism.md)).
|
||
- The tracker is the single source of truth for spec *and* ticket state — no shadow status
|
||
file. Stage reports (pipeline-stages) update the issue via comments/labels rather than a
|
||
separate os-sdlc-owned record.
|
||
## Grilled decisions (2026-07-17)
|
||
|
||
- **Wayfinder subsumes levels.** No DeltaRefinery-style explicit level hierarchy. A big
|
||
plan becomes a wayfinder decision map on the issue tracker: typed sub-issues
|
||
(research / grilling / prototype / task), blocking relationships between them, each
|
||
sized to one agent session; when all close, the map feeds `to-spec`. Blocking edges
|
||
express what levels used to; this drops the rigidity the DeltaRefinery retrospective
|
||
flagged as a failure mode.
|
||
- **Skill adoption verdicts:**
|
||
- **wayfinder — adapt** (keep shape, swap substrate): concept intact — decision map as
|
||
issues, four ticket types, blocking edges, one-session sizing — but every tracker
|
||
interaction goes through os-backlog's `issue-create`/`issues` CLI + tracker key, with
|
||
the cc-os label taxonomy. Verbatim was never on the table: composability with
|
||
os-backlog is a hard constraint (ADR-0037), and Pocock's prose bakes in
|
||
GitHub-specific plumbing (sub-issues, `gh` syntax) Forgejo can't honor.
|
||
- **grill-with-docs — skip; reuse the global `grilling` skill**, both invoked directly
|
||
for small plans and from wayfinder's grilling-type tickets. One grill implementation,
|
||
no drift between copies; the never-ask-twice lookup gate wraps it in one place.
|
||
Accepted cost: os-sdlc depends on a personally-installed global skill — fold a copy
|
||
into the plugin only if os-sdlc ever ships beyond the user's machines.
|
||
- **to-spec / to-tickets — adapt both**: Pocock's semantics (spec = destination,
|
||
tickets = journey) on the os-backlog substrate; all writes via `issue-create` with
|
||
the tracker key; spec→ticket linkage uses plain issue references that work on both
|
||
Forgejo and GitHub; templates are ours (below). Scope note (2026-07-17): os-sdlc's
|
||
`to-spec` does NOT replace the globally installed `to-prd` — os-sdlc is
|
||
software-development specific, while `to-prd` remains the general-purpose PRD
|
||
publisher for non-SDLC work. They coexist; the namespaced invocation
|
||
(`/os-sdlc:to-spec`) keeps them unambiguous.
|
||
- **Spec issue template — lean four-section.** Ticket-level detail lives in tickets, not
|
||
the spec, so the spec stays stable while tickets churn. Labels: `spec` + priority;
|
||
tickets reference it as `spec: #NN`.
|
||
|
||
```md
|
||
# <feature name> [spec]
|
||
|
||
## Destination — what exists when done, 3-6 sentences, observable behavior
|
||
## Settled decisions — every choice an implementer must not relitigate (ADR-NNNN refs)
|
||
## Out of scope — deferred items + where they went (horizon doc, issue #NN)
|
||
## Sources — wayfinder map root #NN, grill transcripts, vault notes, ADRs
|
||
```
|
||
- **Ticket issue template — testable assertions, one-run slice.** Acceptance criteria are
|
||
observable given/when/then assertions the test-writer stage converts to tests
|
||
near-mechanically — batched at one-ticket grain (the DeltaRefinery lesson: drop
|
||
per-example granularity, keep mechanical verification). Sizing rule: a thin end-to-end
|
||
slice fitting one `/implement` run (one worktree, one branch, one review); if the
|
||
criteria won't fit in 3–7 assertions, split the ticket.
|
||
|
||
```md
|
||
# <slice name> [ticket]
|
||
spec: #NN
|
||
|
||
## Slice — one sentence: the thin end-to-end path added; demoable alone
|
||
## Acceptance criteria — 3-7 "Given <state>, when <action>, then <observable result>"
|
||
checkboxes, each testable without human judgment
|
||
## Non-goals — adjacent behavior deliberately left to #NN
|
||
## Notes for implementer (optional) — known seams, files, gotchas
|
||
```
|
||
|
||
## Sources
|
||
|
||
- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
|
||
- ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
|
||
- `plugins/os-sdlc/OVERVIEW.md`
|
||
- SecondBrain vault: `matt-pocock-skills-v1-1-changes.md`
|
||
- `plugins/os-backlog/` (tracker key, `issue-create`/`issues` CLI)
|
||
- 2026-07-16 design session (this doc's origin); 2026-07-17 grill session (decisions above)
|