# 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 # [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 # [ticket] spec: #NN ## Slice — one sentence: the thin end-to-end path added; demoable alone ## Acceptance criteria — 3-7 "Given , when , then " 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)