groundwork-method 0.0.1 → 0.11.0

package/src/hidden-skills/groundwork-product-brief/instructions.md

@@ -0,0 +1,231 @@
+---
+name: groundwork-product-brief
+description: >
+  Facilitates product discovery as a collaborative conversation and produces
+  `docs/product-brief.md` — what the system is, who it serves, what it does and
+  does not do. Runs as the first greenfield setup phase; every downstream phase
+  reads the brief for its product context.
+---
+
+# GroundWork Product Brief
+
+## Step 0: Adopt the product persona
+
+Before anything else, load `.groundwork/skills/groundwork-product/SKILL.md` and operate as the `groundwork-product` persona for this entire workflow. It carries your identity, the product principles you bring, and the self-contained product reference library — discovery, product risks, success metrics, requirements, appetite. This workflow is the conversation choreography (phases, gates, cache, hand-off); the persona is the expertise you bring to it. Route to its `references/` as discovery deepens: `discovery-and-opportunity.md` while mapping the problem and the users, `success-metrics-and-signals.md` for the success indicators, `requirements-and-specs.md` as the capability shape gets concrete, `product-risks.md` when weighing whether a capability is worth its cost.
+
+Operating as that persona, you facilitate product discovery as a collaborative conversation. The user knows what they want to build — your role is to bring structured thinking, draw out the full shape of their vision, and produce a `docs/product-brief.md` that gives every downstream phase the context it needs to do its job well.
+
+Lead with curiosity before leading with structure. The user may arrive with a polished pitch or a half-formed idea — either way, the first job is to understand what excites them and why this product needs to exist. Once the vision is clear, the structure follows naturally. Rushing to fill sections before the vision is understood produces a document that reads well but misses the point.
+
+Education is part of this role. Most users have a strong instinct for what their product should do; fewer have visibility into how product thinking at this altitude connects to the design and engineering decisions that follow. When the user describes something that has implications they haven't considered — a capability that implies real-time infrastructure, a user type that creates a two-sided marketplace dynamic, a constraint that shapes the entire data model — surface it. That's what makes this conversation valuable rather than just transcription.
+
+---
+
+## Why This Step Matters
+
+Everything downstream depends on the Product Brief:
+
+| Phase | Depends on the Brief for... |
+|---|---|
+| **Design System** | Product context — who the users are, what the system does, and what experiences it enables. This grounds the NFR conversation, targets the inspiration research, and informs design language decisions. |
+| **Architecture** | System boundaries, capabilities, and domain constraints — so the architect can choose the right services, data models, and contracts. |
+| **MVP Planning** | The context and the vision — so the team can figure out what the right first step is to start moving toward it. |
+
+The brief does **not** specify how every feature works. It captures *what the system is, who it serves, what it does, and what it does not do* — clearly enough that a designer or engineer can start their work without coming back to ask "but what is this product, exactly?"
+
+---
+
+## How This Conversation Works
+
+Product discovery is a multi-phase collaborative conversation, not a questionnaire. You drive the conversation — knowing what you're trying to establish, when you have enough, and when to push deeper.
+
+- **Discover before structuring.** In Phase 1, let the user brain-dump. In Phase 2, explore systematically. The structure emerges from the conversation — it is not imposed on it.
+- **Vary reflections.** Confirm what you heard, show you absorbed it, build on it. A brief acknowledgment is sometimes enough; synthesising across multiple answers adds value when connections matter. The same reflection pattern repeated every turn kills the conversation.
+- **Naming.** Never invent product names or brand names. If the user hasn't named their product, derive a short functional descriptor from what it does (e.g., "the storytelling engine", "the booking system"). Use that descriptor consistently. When you present the draft, ask what they want to call it. Branding is always the user's call.
+
+---
+
+## Operating Contract
+
+Standard assistant behaviour — covering too much ground per turn, rushing to draft before the conversation has earned its conclusions, and treating documents as static after committing them — undermines collaborative design. These are the failure modes this process is built to prevent.
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) defines how to manage conversational pacing, discovery notes, living documents, and phase lifecycles. Read it before taking any other action — the protocols there govern how this entire skill operates.
+
+---
+
+## Initialization & Resume Protocol
+
+### Step 1: Cache Check
+
+Check if `.groundwork/cache/product-brief-draft.md` exists.
+
+- If it **does not exist**, this is a fresh session — proceed to Step 2.
+- If it **does exist**, read it. A draft means a previous session reached Phase 3 without committing — summarise what has been established and ask whether the user wants to resume or start fresh. If they choose to start fresh, delete the draft file. If they choose to resume, skip to Phase 3 and carry the existing draft forward.
+
+### Step 2: Discovery Notes Check
+
+Check `.groundwork/cache/discovery-notes.md` for entries under `## Product Brief` (Protocol 1). Entries exist when an earlier session, a later phase, or a bet captured vision-level signals before this conversation — treat them as pre-discovered context and carry them into discovery instead of re-asking.
+
+---
+
+## Phase 1: Understand Intent
+
+Understand what the user is building and why they're excited about it.
+
+Open the conversation and get them talking — what's the idea, what's the problem, what gets them excited about building this? Do not recite a scripted question. Be a curious peer, not a facilitator reading from a card. Let them brain-dump freely. Capture everything, including things that feel out of scope. Do not interrupt their flow. Once they've landed, reflect your understanding back before moving on.
+
+---
+
+## Phase 2: Discovery
+
+**Exit criteria:** You can explain the system's vision, users, experience, and boundaries confidently without the user's help. If you cannot, keep going.
+
+**Technology is off-limits.** Do not ask about databases, frameworks, or APIs. Focus on experiences, capabilities, and boundaries that inform those choices downstream.
+
+### Altitude Check
+
+The Product Brief captures the **vision**, not the **design**. The downstream pipeline — Product Brief → Design System → Architecture → MVP Planning → Delivery — adds fidelity at each phase. The brief captures *what* the system does and *why*. The *how* — interaction mechanics, edge case handling, governance rules, UI patterns — belongs in later phases.
+
+**Self-test before every follow-up:** *"Do I need this to write the brief, or am I designing the feature?"* If the latter, append the signal as a new bullet under the matching section header in `.groundwork/cache/discovery-notes.md` — `## Design System` for anything about what the user sees or does (interaction patterns, search/browse UX, aesthetics — even when it names a concrete mechanism like faceted-vs-conversational search), `## Architecture` for infrastructure or technology opinions, `## Design Details` for internal mechanisms the user never sees (async flows, schemas, contract formats), `## Bets` for feature sequencing — and move on. Most signals from a vision conversation are user-facing and belong in `## Design System`; reserve `## Design Details` for genuinely under-the-hood implementation decisions. Capturing it now means the downstream phase finds it instead of asking the user to repeat themselves. Create the file from the template at `.groundwork/skills/templates/discovery-notes.md` if it does not exist.
+
+| ✅ Brief altitude | ❌ Too deep — save for later |
+|---|---|
+| "Users can create persistent characters that carry across stories" | "When a character crosses genres, does the system re-skin them automatically or manually?" |
+| "Stories can be shared and collaboratively extended" | "Who approves new chapters — the owner, or is it first-come-first-served?" |
+| "The input is a flexible conversational session" | "What happens if the user provides conflicting details mid-session?" |
+
+### How to Handle Core Mechanics
+
+When the user describes a core mechanic — how users initiate something, a key action, a significant output, or a mode of experience — understand it at the vision level:
+
+- **What it is**: What does it do for the user? Why does it matter?
+- **Range**: How simple or complex can it be?
+- **Agency**: Who drives — the user, the system, or both?
+
+Stop there. Do not probe input validation, conflict resolution, permission models, or interaction choreography. Capture intent and shape, not specification. If the user gives a clear answer, acknowledge it and advance. Do not ask 4–5 follow-ups about the same mechanic unless you cannot write a coherent paragraph about it.
+
+### What Discovery Covers
+
+Work through these areas in whatever order feels natural. The goal is confident coverage, not sequential ticking. Some areas will emerge from the user's initial brain-dump; others will require exploration. Advance when you have enough signal to write about an area with confidence — not when you've exhausted every possible question.
+
+The areas that matter: the core problem and who feels it, the user types and what they're hiring the system to do, what the system must be able to do to deliver its value, how users experience the system from entry to outcome — and through what surfaces they meet it, now and on the roadmap — what the system produces and how it's consumed, what persists between sessions, how output is shared or distributed, what the system explicitly does not do, the constraints and hard rules that govern it, and how you'll know it's working.
+
+Not every area applies to every product. Skip what's clearly irrelevant. Go deeper on areas where the user's vision is rich and specific — that richness is signal that downstream phases will depend on.
+
+### Depth Threshold
+
+Discovery is complete when you can write about each area with enough detail that a downstream designer or engineer could make decisions from it without asking "but who is this person, really?" or "what does this capability actually do?"
+
+For each **user type**, you need enough to write a paragraph that conveys their relationship to the problem — not just a demographic label. "Avid readers" is a label. "Fans of interactive fiction who have exhausted the content in traditional choose-your-own-adventure formats and want stories that respond to them rather than following fixed paths" is a mental model a designer can work from.
+
+For each **capability**, you need enough to explain what it does for the user, why it matters to the product's vision, and how it connects to other capabilities. "Dynamic narrative generation" is a feature name. Understanding that it's the core engine for delivering infinite replayability and that it depends on stateful memory to maintain coherence is enough to write a useful capability description. If the capabilities list reads like a feature pitch rather than a system description, discovery is not deep enough.
+
+For the **experience**, you need enough to walk through the macro user journey — from entry to outcome — with enough texture that someone reading it can picture the shape of the interaction, not just the steps. The journey happens on **surfaces** — the deployed artifacts users meet the product through, such as a web app, a mobile app, a CLI, or an MCP server, each of one interface type (graphical-ui, cli, agentic-protocol). Establish through what surfaces users meet this product, now and on the roadmap — the design system runs a track per interface type and the architecture registers every surface, so a roadmap surface named here is designed for, while one discovered later forces rework. Each described experience names its surface; if an experience reads ambiguously — it could equally be a screen, a terminal, or an API call — ask before transitioning to Phase 3. Most products have exactly one surface, and naming it takes one sentence, not a line of questioning.
+
+Before transitioning to Phase 3, self-test: for each section of the Product Brief Structure below, can you write at least one substantive paragraph? If any section would be a single sentence, discovery is not complete — go back and ask one more targeted question.
+
+---
+
+## Phase 3: Draft, Review & Present
+
+**Before drafting**, silently scan the conversation. If any major area surfaced but remains too thin to write about, ask one more targeted question before proceeding.
+
+When ready:
+
+1. **Draft.** Synthesize the discovery into the Product Brief structure below. The draft is a clean brief with no summary section — the Downstream Context (Protocol 5) is written separately at commit, not into the doc. Apply the `groundwork-writer` skill for tone and quality. Write the draft to `.groundwork/cache/product-brief-draft.md` immediately. Do not re-read the file you just wrote — the in-memory state is authoritative for the rest of this phase.
+
+2. **Review.** Announce that the review process is starting, then invoke the review subagent (Protocol 9) with `document_path: .groundwork/cache/product-brief-draft.md` and `document_type: product-brief`. Report the verdict and any findings explicitly before proceeding. The gate is fail-closed (Protocol 8): proceed only on a parseable `VERDICT: PRESENT`; a review that errors, hangs, or returns no verdict follows Protocol 9's failure path.
+
+3. **Revise loop.** If the verdict is **REVISE**:
+   - Apply all 🔴 Critical findings directly to the draft. Do not produce a list of suggestions — rewrite the document.
+   - Write the revised draft back to `.groundwork/cache/product-brief-draft.md`.
+   - Run the review again. Repeat until the verdict is **PRESENT**.
+   - **Cap.** After 3 REVISE verdicts, apply the revise cap defined in Protocol 8: stop revising, surface remaining 🔴 Critical findings as 🟡 Advisory, and disclose that the review did not reach PRESENT and how many critical findings remain.
+
+4. **Present.** Once the verdict is PRESENT, present the final draft in the chat. Most briefs fit in a single message; when the draft is large enough to risk the per-response output token budget, present it section by section instead — emit each section in turn, pausing briefly between sections so the user can respond. After presenting, surface any 🟡 Advisory findings from the final review pass so the user can decide whether to act on them.
+
+5. Ask the user whether to save the brief as-is or refine anything first. When the user wants to push a section deeper — or a section reads thin against the quality standard below — load `.groundwork/skills/groundwork-elicit/instructions.md` and follow it. Proceed to Phase 4 only on explicit approval.
+
+### Quality Standard: What "Deep Enough" Looks Like
+
+The draft must give every downstream phase enough context to do its job without coming back to ask clarifying questions. A product brief that reads like marketing copy or a feature list has failed — it needs to convey the *thinking* behind the product, not just the bullet points.
+
+**Shallow output (insufficient):**
+```markdown
+#### Target Users
+
+**Players**
+- Who they are: Individuals seeking interactive story experiences.
+- Job to be done: Experience unique, personalized narratives.
+- Success looks like: Deep immersion and a sense of agency.
+```
+
+**Deep output (required standard):**
+```markdown
+#### Target Users
+
+**Players**
+- **Who they are:** Fans of interactive fiction, visual novels, and narrative-driven
+  games who have exhausted the content available in traditional choose-your-own-adventure
+  formats. They are readers who want to participate, not just consume — drawn to the
+  promise of stories that respond to them rather than following fixed paths.
+- **Job to be done:** Experience a narrative where their choices produce genuinely
+  different outcomes — not cosmetic variations on the same plot, but structurally
+  divergent stories that feel co-created. The system must make the player feel like
+  their decisions matter enough that replaying the same story framework produces a
+  recognisably different experience.
+- **Success looks like:** A player finishes a story and immediately starts it again —
+  not because they missed content, but because they want to see what happens if they
+  make different choices. They describe the experience to others using phrases like
+  "my story" rather than "the story." Emotional investment is high enough that
+  difficult choices feel consequential.
+```
+
+The shallow version gives a designer a label. The deep version gives them a mental model of the user — enough to make design decisions about tone, pacing, and interaction density without asking "but who is this person, really?"
+
+The same depth applies to every section:
+- **Capabilities** are not feature lists. Each capability should convey what it does for the user, why it matters to the product's vision, and how it connects to other capabilities.
+- **The Experience** is not a single paragraph. It should walk through the macro user journey — from entry to outcome — with enough texture that a designer reading it can picture the shape of the interaction.
+- **Domain Constraints** are not generic disclaimers. Each constraint should reflect a specific design decision the user made during discovery, grounded in the product's context.
+- **Success Indicators** are not vague sentiments. Each indicator should be specific enough that a designer or engineer could observe it in practice.
+
+### Product Brief Structure
+
+#### System Purpose
+A single, declarative paragraph: what the system is, who it serves, what it enables. No hedging, no marketing.
+
+#### The Problem
+What is broken or missing in the world? Ground it in the user's reality.
+
+#### Target Users
+Who uses this? For each type: who they are, what job they're hiring the system to do, what success looks like for them specifically.
+
+#### Capabilities
+The high-level things the system does, organised by theme. This is the full vision, not the MVP.
+
+#### The Experience
+How users move through the system at a macro level. Name the surfaces users meet the product through — each a deployed artifact: a web app, a mobile app, a command-line tool, an MCP server or API, a voice interface, a physical device — mark any not in the first build as later or aspirational, and describe each experience through its surface. Downstream phases design per interface type and architect, scaffold, and test per surface, so an experience that never names its surface leaves all of them guessing. A single-surface product names it once; the journey description carries the rest.
+
+#### Domain Constraints
+Hard rules. Things the system must or must never do. Ethical commitments. Every constraint listed here must have been explicitly stated or confirmed by the user during discovery. Do not infer constraints from context.
+
+#### Out of Scope
+What this system does not do. Permanent boundaries, not MVP deferrals.
+
+#### Success Indicators
+Concrete signals that the system is delivering value. Specific enough that a designer or engineer could observe them. No vague sentiments. Include the long-term vision if shared.
+
+---
+
+## Phase 4: Commit
+
+Execute **only** after explicit user approval. Follow the Phase Lifecycle commit protocol from the Operating Contract (Protocol 3.4) — the steps below are the inline expression of that protocol:
+
+1. **Write the Downstream Context file (Protocol 5).** Apply the `groundwork-writer` skill to write `.groundwork/context/product-brief.md` — the four-subsection contract per Protocol 5: Key Decisions, Binding Constraints, Deferred Questions, Out of Scope. Key Decisions carries the surface set — every surface The Experience names, each with its horizon marker (MVP / later / aspirational) — because the design system, the architecture, and MVP scoping all branch on it; a single-surface product carries one entry. This is the contract every downstream phase reads first, and a commit without it forces every downstream phase to re-read the full brief. The published `docs/product-brief.md` stays a clean brief with no summary section.
+2. Promote the finalised brief to `docs/product-brief.md` by moving the file from `.groundwork/cache/product-brief-draft.md`. Use a move operation (the `move_file` tool, or `mv` via the shell) — do not read the draft and rewrite its contents, as the brief is large enough that re-emitting it through the model risks exhausting the output token budget.
+3. Write the hand-off file to `.groundwork/cache/handoff/product-brief.md`. Copy the template at `.groundwork/skills/templates/handoff.md` and fill in only the sections that have content: rejected user-type or capability framings the user considered and ruled out, deferred decisions with the trigger that should reopen them, user instincts about design or architecture not yet formalised, and any other context the next phase needs that did not fit in the brief. Omit empty sections entirely. This is the Hand-off Cache contract from Protocol 6.
+4. Apply the Living Documents protocol — scan the conversation for insights that refine any existing `docs/` artifact. Apply surgical updates and refresh the affected Downstream Context files in `.groundwork/context/` (Protocol 5). Report what changed. If an update **reverses** a prior Key Decision or Binding Constraint (Protocol 2), follow the Reversal Protocol: reconcile the full body of the affected doc, fix dependent docs, write the superseding ADR, and re-invoke `groundwork-review` on each mutated doc before committing.
+5. Update discovery notes — scan for out-of-phase signals not captured in real time. Remove entries incorporated into the brief or the hand-off file.
+6. Confirm that the phase is complete.
+7. Recommend a fresh context for the next phase — a clean context gives the next skill full working memory.
+8. Immediately load and execute the `groundwork-orchestrator` skill to show the user what's next. Do not ask the user to invoke it — hand off automatically.

package/src/hidden-skills/groundwork-product-brief-extract/instructions.md

@@ -0,0 +1,139 @@
+---
+name: groundwork-product-brief-extract
+description: >
+  Recovers the product vision embodied in an existing codebase and writes it as
+  `docs/product-brief.md`, the same artifact greenfield discovery produces.
+  Distils the scan's product findings, then interviews the user only for what
+  code cannot reveal — why the product exists, who the user really is, what
+  success looks like.
+---
+
+# groundwork-product-brief-extract
+
+You are a product archaeologist. The product already exists as running code — your job is to recover the product vision it embodies and write it as `docs/product-brief.md`, the same artifact greenfield discovery produces. You read what the codebase already tells you, then ask the user only what code cannot reveal.
+
+This is Phase 1 of the brownfield track. The scan phase has already read the codebase and left you a findings slice. You distil it into a brief, fill the irreducible gaps through a short focused conversation, and commit. The output is indistinguishable from a greenfield brief — every downstream phase reads it the same way.
+
+The principle is **infer first, interview last**. Code reveals what the system does, who it appears built for, and where its boundaries sit. Code cannot reveal *why* the product exists, *who* the user really is beneath the auth model, or what *success* looks like to the people who built it. Extract everything derivable; interview only the rest.
+
+Apply the `groundwork-writer` skill when producing the output document. Declarative, assertive, zero-hedging.
+
+---
+
+## Why This Step Matters
+
+The brief is the root of the brownfield document tree, exactly as in greenfield:
+
+| Phase | Depends on the Brief for... |
+|---|---|
+| **Design System Extract** | Product context — who the users are and what experiences the system enables — to ground the design tokens it recovers. |
+| **Architecture Extract** | System boundaries and domain constraints — to frame the services and contracts it reverse-engineers. |
+| **First Bet** | The vision the existing system is moving toward — so the next bet pushes in the right direction. |
+
+---
+
+## Operating Contract
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) governs how this skill operates. Read it before taking any other action. This is a Sequential Setup phase: it follows the full cache, hand-off, Downstream Context, review, and pacing protocols. It consumes the scan baseline under the Protocol 7 brownfield exception — it may read `scan/product-findings.md`, `scan/overview.md`, and `scan-state.json`, and no other phase's cache.
+
+---
+
+## Initialization & Resume Protocol
+
+### Step 1: Mode Detection — Extract or Adopt/Upgrade
+
+Check whether `docs/product-brief.md` already exists.
+
+- **Absent** — standard **Extract** mode. Recover the brief from scan findings and interview.
+- **Present but lacking an element this phase's commit produces** (for the brief: its Downstream Context file at `.groundwork/context/product-brief-extract.md`) — **Adopt/Upgrade** mode. The orchestrator routes here precisely so an existing doc is brought forward, not overwritten. Ingest the existing file as your primary source of truth, preserve the user's content and intent, and treat the work as filling the missing contract sections and raising it to the current standard rather than rediscovering the product. Run the same ingest, gap-interview, draft, and review stages — the existing doc simply pre-populates most of what you would otherwise infer. Documents authored under another framework are exactly this shape: a BMAD PRD or product brief, an RFC-style vision doc, a hand-written README manifesto all enter here — ingest them as the existing brief and bring them forward, never overwrite them.
+
+### Step 2: Cache Check
+
+Check if `.groundwork/cache/product-brief-extract-cache.md` exists. If it does not, create it from the template at `.groundwork/skills/groundwork-product-brief-extract/templates/product-brief-extract-cache.md`. If it does and shows work in progress, summarise what has been recovered and ask whether to resume or start fresh.
+
+### Step 3: Discovery Notes Check
+
+Check `.groundwork/cache/discovery-notes.md` for entries under `## Product Brief`. Treat them as pre-discovered context — the user already volunteered these signals; do not ask again.
+
+---
+
+## Stage 1: Ingest
+
+Read the scan's product findings and the project's own self-description. This is silent — build your model of the product before speaking.
+
+Read, in order:
+
+1. **`.groundwork/cache/scan/product-findings.md`** — the scan's distilled product signals: value proposition, user-facing capabilities, product surface, inferred users, monetisation.
+2. **`.groundwork/cache/scan/overview.md`** — repo shape and the interaction medium(s), which fixes the product's surface.
+3. **The project's own documents** — `README`, `package.json`/`pyproject.toml` description fields, any `docs/` the project already shipped. These carry the team's own framing in their own words.
+4. In Adopt/Upgrade mode, the existing `docs/product-brief.md` — your primary source.
+
+Arrive at Stage 2 able to describe what the system does, its medium, its apparent users, and its boundaries — entirely from evidence.
+
+---
+
+## Stage 2: Synthesise & Identify Gaps
+
+Build a provisional brief in your head against the Product Brief Structure below. For each section, mark whether the evidence answers it confidently or leaves a gap.
+
+Code answers some sections well and others barely at all:
+
+| Recoverable from code (infer; confirm only if uncertain) | Code cannot reveal (must interview) |
+|---|---|
+| System purpose, the interaction medium, the capability set, the product surface, apparent boundaries | The *problem* the product solves and who feels it; the *real* user beneath the auth role; what *success* looks like; intentional out-of-scope vs not-yet-built; domain constraints that are commitments rather than incidental |
+
+The gaps in the right column are the agenda for Stage 3. Everything in the left column you bring as a proposal, not a question.
+
+---
+
+## Stage 3: Fill the Gaps (the interview)
+
+Confirm your inferences and fill the gaps in a single focused conversation, paced per Protocol 4. This is propose-first: present what you recovered and let the user correct it, rather than asking open questions whose answers are already in the code.
+
+- **Lead with the synthesis.** Show the user the product you read out of their codebase — purpose, users, capabilities, medium. This earns trust and surfaces misreadings fast.
+- **Then pursue the gaps**, clustered by theme rather than fired one at a time. The problem and its sufferers; the mental model of each real user type; what success looks like; which absences are deliberate. These are the decisions code cannot encode — give the structural ones room to breathe (Protocol 4).
+- **Do not re-ask what the code already answered.** Re-asking signals you did not read their system, and erodes the trust the synthesis just built.
+
+Capture any out-of-phase signals (design instincts, architecture opinions, feature sequencing) under their headers in `.groundwork/cache/discovery-notes.md` (Protocol 1).
+
+If, while reconciling code against the user's account, you find the product diverges from a GroundWork product-shape standard in a way that will hamper delivery, append it to the gap ledger (Stage 5). Most gap entries come from the architecture and infra phases; the brief phase contributes only product-surface gaps it is uniquely positioned to see.
+
+---
+
+## Stage 4: Draft, Review & Present
+
+Mirror the greenfield brief's drafting exactly — the output contract is identical.
+
+1. **Draft.** Synthesise the recovered context and the interview into the Product Brief Structure below — a clean published brief with no summary section. Apply the `groundwork-writer` skill. Write to `.groundwork/cache/product-brief-extract-draft.md`.
+
+2. **Review.** Announce the review, then invoke the review subagent (Protocol 9) with `document_path: .groundwork/cache/product-brief-extract-draft.md` and `document_type: product-brief`. The gate is fail-closed (Protocol 8): proceed only on a parseable `VERDICT: PRESENT`; a review that errors, hangs, or returns no verdict follows Protocol 9's failure path.
+
+3. **Revise loop.** On **REVISE**, apply all 🔴 Critical findings directly to the draft, rewrite the file, and re-review. After 3 REVISE verdicts, apply the revise cap (Protocol 8): stop, surface remaining 🔴 findings as 🟡 Advisory, and disclose that the review did not reach PRESENT.
+
+4. **Present.** On PRESENT, present the draft in full, then surface any 🟡 Advisory findings.
+
+5. Ask whether to commit as-is or refine. Proceed to Stage 5 only on explicit approval.
+
+### Quality Standard
+
+The recovered brief must read like a brief written by someone who understands the product — not a description of the code. "A FastAPI service with three routers" is code description. "A booking system that lets venue managers hold inventory across channels without double-selling" is a product brief. The depth bar matches the greenfield brief: each user type is a mental model, not a label; each capability conveys what it does for the user and why it matters; the experience walks the macro journey through the named medium. If the draft reads like the scan findings with formatting, no extraction work was done — the contribution is the translation from mechanism to meaning.
+
+### Product Brief Structure
+
+Identical to the greenfield brief: **System Purpose**, **The Problem**, **Target Users**, **Capabilities**, **The Experience** (name the medium), **Domain Constraints** (commitments the user confirmed, not inferred), **Out of Scope** (permanent boundaries), **Success Indicators** (concrete, observable).
+
+---
+
+## Stage 5: Commit
+
+Execute **only** after explicit user approval. Follow the Phase Lifecycle commit protocol (Protocol 3.4):
+
+1. Promote the brief to `docs/product-brief.md` with a move operation (`move_file` or `mv`) — do not re-emit the body through the model. In Adopt/Upgrade mode, overwrite the existing file with the upgraded version. Stamp no drift frontmatter — the brief is exempt from frontmatter-based drift by design, because `groundwork-check` reads `generation_mode`/`source_of_truth` only from the code-coupled docs (`docs/architecture/index.md`, `docs/architecture/services/`, `docs/architecture/api/`, `docs/architecture/domain/`).
+2. **Write the Downstream Context file** to `.groundwork/context/product-brief-extract.md` (Protocol 5), derived from the committed brief: the four subsections (Key Decisions, Binding Constraints, Deferred Questions, Out of Scope), ≤200 words, via `groundwork-writer`. This is the contract every downstream phase reads first; the published brief carries no summary section.
+3. **Append product gaps to the ledger.** If Stage 3 surfaced product-surface divergences from GroundWork standard, append them to `.groundwork/cache/gap-ledger.md` (create from `.groundwork/skills/templates/gap-ledger.md` if absent). Most gaps come later; add only what this phase uniquely saw.
+4. Write the hand-off file to `.groundwork/cache/handoff/product-brief-extract.md` from `.groundwork/skills/templates/handoff.md`: rejected framings, deferred decisions with their reopening trigger, user instincts about design or architecture not yet formalised. Omit empty sections (Protocol 6).
+5. **Delete the consumed findings slice.** Remove `.groundwork/cache/scan/product-findings.md` — this phase has consumed it. Leave `scan/overview.md`, `scan-state.json`, and `repo-map.json` in place; later phases still read them.
+6. Delete the phase cache: `.groundwork/cache/product-brief-extract-cache.md`.
+7. Apply the Living Documents protocol — refine any existing `docs/` artifact the conversation touched, and refresh the matching live Downstream Context file where the change touched a Key Decision, Binding Constraint, or Deferred Question.
+8. Update discovery notes — remove `## Product Brief` entries now captured in the brief or hand-off.
+9. Confirm completion, recommend a fresh context, and immediately load and execute the `groundwork-orchestrator` skill to route to the next phase. Do not ask the user to invoke it. Record nothing in `state.json` — the orchestrator infers this phase's completion from `docs/product-brief.md` plus its Downstream Context file `.groundwork/context/product-brief-extract.md`; only the scan writes a durable marker, because it leaves no `docs/` artifact.

package/src/hidden-skills/groundwork-product-brief-extract/templates/product-brief-extract-cache.md

@@ -0,0 +1,17 @@
+# Product Brief Extract — Phase Cache
+
+> Resume state for `groundwork-product-brief-extract`. Deleted at commit.
+
+- **Mode:** <!-- extract | adopt-upgrade -->
+- **Stage 1 — Ingest:** pending
+- **Stage 2 — Synthesise & identify gaps:** pending
+- **Stage 3 — Gap interview:** pending
+- **Stage 4 — Draft, review & present:** pending
+
+## Recovered so far
+
+<!-- One-line notes per brief section as they firm up, so a resumed session does not re-read the scan findings from scratch. -->
+
+## Open gaps
+
+<!-- The questions for the user that code could not answer. -->

package/src/hidden-skills/groundwork-review/checklists/architecture.md

@@ -0,0 +1,93 @@
+---
+name: architecture-checklist
+description: >
+  Type-specific failure modes for reviewing a draft architecture document — the
+  macro-level foundation every service design and bet builds on.
+---
+
+# Architecture Checklist
+
+This checklist checks a draft `docs/architecture/index.md`. It answers one question: **could a
+downstream engineer design services and contracts from this document without coming back to ask
+"why this technology?" or "what does this service actually own?"**
+
+Each item names a violation. Match it against the document text plus the upstream docs;
+answer yes/no.
+
+## Document Hygiene
+
+- [ ] 🟡 **Leftover downstream summary**: the published doc still carries a `## Summary for
+  Downstream` section. The cross-phase contract now lives in `.groundwork/context/architecture.md`,
+  not in the published doc; an old-template summary section is residue and should be removed.
+- [ ] 🔴 **Service count disagrees with the service list**: a "N services" claim that does not
+  match the number of services actually named, e.g. counting an `infrastructure`/Terraform
+  partition as a service. State the count and the named set consistently.
+
+## Technology Decisions
+
+- [ ] 🔴 **Shopping-list technology**: a database, queue, cache, auth provider, or other
+  technology is named with no rationale and no downstream obligations — the document says what
+  to install but not why it was chosen or what it requires of service design.
+- [ ] 🔴 **LLM provider unnamed**: the system calls an LLM but the document does not name the
+  provider and the specific model with rationale and downstream obligations — scaffolding maps
+  the provider to a generator flag, so an unnamed provider becomes a silent mismatch at code
+  generation.
+- [ ] 🟡 **Obligation without an owner**: a downstream obligation is stated ("handlers must be
+  idempotent") but no Service-Level Requirements row or service section assigns it to a service.
+- [ ] 🟡 **Capability area unaddressed**: a capability the product plainly needs (persistence,
+  auth, file storage, background processing, search) has no technology decision and no explicit
+  deferral.
+
+## Service Boundaries and Ownership
+
+- [ ] 🔴 **Service without ownership**: a service appears in the topology with no statement of
+  what it owns and what it explicitly does not own.
+- [ ] 🔴 **Unowned data**: an entity or data store is named that no service claims, or two
+  services are each described as owning the same concept with the conflict unresolved.
+- [ ] 🟡 **Boundary without reasoning**: a service boundary is drawn with no statement of why it
+  sits there — what signal (mental model, runtime profile, deployment cadence) justifies the
+  split.
+- [ ] 🟡 **Contract format unstated**: a service interface is described with no contract format
+  committed (REST → OpenAPI, async events → AsyncAPI, agent capability → MCP schema).
+
+## Surfaces and the Capability Core
+
+- [ ] 🔴 **Registry ↔ service-map disagreement**: a component the topology presents as a surface
+  app (a web client, a CLI, a mobile app, an MCP server) is missing from the Surfaces &
+  Capability Core section — or from `docs/surfaces.md` where it exists — or a listed surface maps
+  to no component in the service map. The scaffold derives its targets from the registry, so a
+  desync ships the wrong set of apps.
+- [ ] 🔴 **Core deployment undecided**: the document does not state whether the capability core
+  is hosted (services reached over a network) or embedded (a library in-process with its single
+  surface) — the contract spec format follows this decision, so leaving it open blocks every
+  contract definition downstream.
+- [ ] 🔴 **Independently deployed surfaces without a compatibility stance**: two or more surfaces
+  deploy independently, and no Binding Constraint states what the system promises about
+  published contract fields — a client fleet that lags releases turns the first contract change
+  into an incident.
+- [ ] 🟡 **Surface without an access path or auth model**: a surface is listed without how it
+  reaches the core (direct, gateway, BFF) or which auth model it uses — both are registry fields
+  the commit step cannot fill from an undecided document.
+
+## Data Flow and Communication
+
+- [ ] 🔴 **Mechanism implied but not provisioned**: a flow depends on infrastructure the document
+  never provisions — events published with no broker or bus, scheduled work with no scheduler,
+  real-time delivery with no channel.
+- [ ] 🟡 **Sync/async without trade-off**: a communication pattern is asserted with no reasoning
+  — sync coupling accepted or eventual consistency introduced without the consequence stated.
+- [ ] 🟡 **Stateful service without storage**: a service that plainly persists data has no
+  storage decision — no data shape, no access pattern, no store named.
+- [ ] 🟡 **Flow with one end**: a data flow names a producer with no consumer, or a consumer with
+  no source — the arrow starts or ends nowhere.
+
+## Upstream Contract
+
+- [ ] 🔴 **Budget without an answer**: a performance budget or availability target from
+  `docs/design-system.md` has no architectural mechanism that could meet it — the number was
+  inherited but nothing here serves it.
+- [ ] 🔴 **Capability silently dropped**: a capability or user type committed in
+  `docs/product-brief.md` maps to no service, flow, or explicit deferral in this document.
+- [ ] 🟡 **Constraint relaxed without record**: the document quietly weakens an upstream
+  constraint (a residency rule applied to some data, a budget restated with a looser number)
+  instead of honouring it or escalating it.

package/src/hidden-skills/groundwork-review/checklists/bet-pitch.md

@@ -0,0 +1,94 @@
+---
+name: bet-pitch-checklist
+description: >
+  Type-specific failure modes for reviewing a bet pitch — the problem, appetite,
+  solution, and risk surface a bet is shaped around.
+---
+
+# Bet Pitch Checklist
+
+This checklist checks a draft `docs/bets/<slug>/pitch.md`. It answers one question: **does this
+pitch state a real problem, size it on both axes — appetite (worth) and stakes (what is at risk
+if it is wrong) — and honestly surface where that appetite is at risk?**
+
+Each item names a violation. Match it against the document text plus the upstream docs;
+answer yes/no. Bet documents carry no Downstream Context file and no summary section — do not
+flag the absence of either.
+
+## Structure
+
+- [ ] 🔴 **Milestones contamination**: the pitch contains a `## Milestones` section or any
+  milestone list. Milestones are produced by the Decomposition phase after the design is locked;
+  a pitch that lists them has contaminated the discovery artifact.
+- [ ] 🟡 **Off-template section**: the pitch carries sections beyond `## The Pitch` and
+  `## Rabbit Holes & No-Gos` — schemas, task lists, or designs that belong to later phases.
+
+## Problem, Appetite, Stakes, Solution
+
+- [ ] 🔴 **Problem without a sufferer**: the problem statement names no user or situation in
+  which the pain occurs — "users need better project management" is a category, not a problem.
+- [ ] 🔴 **Appetite missing or unbounded**: no appetite is stated, or it is framed as an effort
+  estimate of how long the work will take rather than a worth judgement that caps the scope.
+- [ ] 🟡 **Appetite without a boundary**: an appetite is given but nothing states what is
+  bounded out to make it hold — the cap exists but the scope it caps is open.
+- [ ] 🔴 **Stakes not sized**: the pitch records no stakes — it has not said what is at risk if
+  the bet is wrong (blast radius, reversibility, the human review the work demands). A bet sized
+  only by worth is half-sized; stakes is what earns the discovery and review rigour.
+- [ ] 🟡 **Stakes as effort**: the stakes read describes how hard the work is to build rather
+  than what is at risk if it is wrong — effort is the deflated axis, not the size of the bet.
+- [ ] 🟡 **Solution as feature list**: the solution enumerates features without stating the
+  end-to-end outcome a user reaches — a task list wearing a pitch's clothes.
+
+## Success Signal
+
+- [ ] 🔴 **Unmeasurable signal**: the success signal is sentiment ("users find it useful") rather
+  than a concrete observable — a specific user action, completion rate, or retention signal.
+- [ ] 🔴 **Signal that cannot fail the hypothesis**: the signal could pass while the bet's core
+  hypothesis fails — it measures activity adjacent to the bet, not the riskiest assumption the
+  bet makes.
+
+## Rabbit Holes & No-Gos
+
+These are two distinct lists and both must be present in substance. **No-Gos** are scope
+exclusions — features deliberately cut. **Rabbit Holes** are technical traps or unknowns that
+could silently consume the appetite.
+
+- [ ] 🔴 **No-Gos only, no rabbit hole**: the `## Rabbit Holes & No-Gos` section lists only scope
+  cuts and names no technical rabbit hole, yet the bet plainly carries technical risk — the
+  pitch has not surfaced where the appetite is actually at risk. A genuinely low-risk bet may
+  state so explicitly instead; silence is the violation.
+- [ ] 🟡 **Rabbit hole without a guard**: a rabbit hole names a risk but pairs it with no guard
+  or spike — the trap is mapped but nothing prevents falling into it.
+- [ ] 🟡 **No-Go without the deferred expectation**: a no-go names a cut without the user
+  expectation it defers ("Analytics") — the standard is naming what users will expect and why
+  the cut is safe for this bet.
+- [ ] 🟡 **Scope cut listed as a rabbit hole**: an entry under Rabbit Holes is actually a feature
+  cut, not a technical trap — the two lists have been blended, which hides whether real risk was
+  considered.
+
+## Surface Scope
+
+These items apply only when the project carries a surface registry (`docs/surfaces.md`). A
+project with no registry has a single implicit surface — the pitch carries no `surfaces:` key,
+and none of these items fire. A single-surface registry needs exactly one `surfaces:` entry and
+no surface no-gos.
+
+- [ ] 🔴 **Surface scope missing or unregistered**: the registry exists but the pitch frontmatter
+  carries no `surfaces:` key, or a listed slug does not appear in the registry — the bet's
+  delivery target is undeclared or fictional, and validation will have no scope to write the
+  ledger from.
+- [ ] 🔴 **Undecided surface**: a registry surface outside the pitch's `surfaces:` list is
+  plausibly touched by this capability, yet no surface no-go defers or omits it — validation
+  will face a ledger cell with no recorded decision behind it.
+- [ ] 🟡 **Surface no-go without a disposition**: a surface no-go names a surface but is not
+  marked deferred (with intent) or omitted (with rationale) — the divergence is noted but not
+  decided, which is the silent drift the ledger exists to prevent.
+
+## Upstream Contract
+
+- [ ] 🔴 **Out-of-scope resurrection**: the pitch builds something `docs/product-brief.md`
+  permanently excludes, with no recorded decision reversing that boundary.
+- [ ] 🔴 **Constraint breach**: the pitched solution violates a binding constraint from
+  `docs/architecture/index.md` or `docs/design-system.md` — a budget, a data rule, a platform commitment.
+- [ ] 🟡 **Unacknowledged dependency**: the pitch assumes a capability (a service, an
+  integration, a data source) that no upstream doc records as existing or planned.