From 19846f040098dc1b73c35d4325b49e43b2cc46ec Mon Sep 17 00:00:00 2001 From: jared Date: Fri, 17 Jul 2026 16:41:49 -0400 Subject: [PATCH] =?UTF-8?q?os-sdlc:=20spec-and-ticket-layer=20grilled=20?= =?UTF-8?q?=E2=80=94=20wayfinder=20subsumes=20levels,=20templates=20fixed?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolves all three open questions (2026-07-17 grill): wayfinder subsumes DeltaRefinery-style levels; adopt verdicts (adapt wayfinder/to-spec/to-tickets to the os-backlog substrate, skip grill-with-docs in favor of the global grilling skill); lean four-section spec template + given/when/then ticket template sized to one /implement run. Scope note: to-prd coexists — os-sdlc is software-development specific (Forgejo #81 closed). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01PG3SoJqPk1xCyQrhVZZHFf --- plugins/os-sdlc/OVERVIEW.md | 6 +- .../reference/spec-and-ticket-layer.md | 69 +++++++++++++++---- 2 files changed, 60 insertions(+), 15 deletions(-) diff --git a/plugins/os-sdlc/OVERVIEW.md b/plugins/os-sdlc/OVERVIEW.md index 809c834..33cab11 100644 --- a/plugins/os-sdlc/OVERVIEW.md +++ b/plugins/os-sdlc/OVERVIEW.md @@ -57,7 +57,7 @@ graph TD | Node | Status | One-liner | |---|---|---| -| [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) | settled direction | Git issues (Forgejo/GitHub per tracker key) are the durable spec layer; Pocock verbs map onto it | +| [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) | settled (grilled 2026-07-17) | Git issues are the durable spec layer; wayfinder subsumes levels; adapt wayfinder/to-spec/to-tickets, reuse global grilling; spec + ticket templates fixed | | [pipeline-stages](reference/pipeline-stages.md) | direction | The v1 tracer bullet: `/implement` → test-writer → red-assert → programmer → green-assert → reviewer → human merge | | [deterministic-gates](reference/deterministic-gates.md) | settled | Hooks, not agents, run tests/lint; red/green asserted mechanically; green command pluggable per project | | [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format | @@ -97,8 +97,8 @@ trusted. Open items live per-node in each doc's "Open questions" — this file carries none. **Grill queue** (decided 2026-07-16): the critical path is -[spec-and-ticket-layer](reference/spec-and-ticket-layer.md) → -[pipeline-stages](reference/pipeline-stages.md) — grill in that order first. +[spec-and-ticket-layer](reference/spec-and-ticket-layer.md) (✅ grilled 2026-07-17) → +[pipeline-stages](reference/pipeline-stages.md) — next up. Then [never-ask-twice](reference/never-ask-twice.md) + [self-improvement-loops](reference/self-improvement-loops.md) (can run in parallel with pipeline build; NAT's formalization ADR is independent), then diff --git a/plugins/os-sdlc/reference/spec-and-ticket-layer.md b/plugins/os-sdlc/reference/spec-and-ticket-layer.md index 7cb8fc7..82a1ebd 100644 --- a/plugins/os-sdlc/reference/spec-and-ticket-layer.md +++ b/plugins/os-sdlc/reference/spec-and-ticket-layer.md @@ -1,6 +1,6 @@ # spec and ticket layer -_Status: settled direction — as of 2026-07-16_ +_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 @@ -35,18 +35,63 @@ issue-tracker state for os-sdlc. - 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. -- Spec and ticket content structure is intentionally not fixed yet (see Open questions) — - the mapping above fixes *where* things live and *what stage produces them*, not their - internal template. +## Grilled decisions (2026-07-17) -## Open questions +- **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`. -- Which Pocock skills (wayfinder, grill-with-docs, to-spec, to-tickets) are adopted - near-verbatim vs. adapted for the git-issues substrate vs. skipped entirely. -- Whether wayfinder subsumes or sits alongside a DeltaRefinery-style level structure - (DeltaRefinery decomposed work into explicit levels; Pocock's wayfinder is looser). -- Concrete spec issue template (sections, required fields) and ticket issue template - (acceptance criteria shape, tracer-bullet slice size). + ```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 @@ -55,4 +100,4 @@ issue-tracker state for os-sdlc. - `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-16 design session (this doc's origin); 2026-07-17 grill session (decisions above)