bigpowers 2.86.5 → 2.86.7

package/.opencode/skills/elaborate-spec/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: elaborate-spec
+model: opus
+description: "Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn \"I want X\" into a concrete spec."
+---
+
+# Elaborate Spec
+
+Turn a rough idea into a clear specification through focused dialogue. No code is written during this skill — the output is shared understanding and a refined problem statement.
+
+> **HARD GATE** — Do NOT proceed with planning or implementation until the problem space is clearly understood. Success criteria, actors, and scope must be explicit before drafting a plan.
+
+## Process
+
+### 1. Listen first
+
+Let the user describe their idea in their own words. Do not interrupt or redirect. Take notes on:
+- The core problem they're trying to solve
+- Who is affected (actors)
+- What success looks like to them
+- Any constraints they've already identified
+
+### 2. Ask clarifying questions
+
+Ask one question at a time. Work through these areas:
+
+**Problem clarity**
+- What is the current behavior (or lack of behavior) that prompted this?
+- Who experiences this problem? How often?
+- What's the cost of not solving it?
+
+**Solution boundaries**
+- What is explicitly IN scope?
+- What is explicitly OUT of scope?
+- Are there existing solutions (internal or external) this replaces or integrates with?
+
+**Success criteria**
+- How will you know this is done?
+- What does the happy path look like end-to-end?
+- What are the key failure modes to handle?
+
+**Constraints**
+- Any performance requirements?
+- Any compatibility constraints (existing APIs, data formats)?
+- Any non-negotiable implementation decisions already made?
+
+### 2.5. Multiple Interpretations (HARD GATE)
+
+> **HARD GATE** — If the request admits ≥2 valid interpretations, do NOT guess. You must list them and ask the user to choose before proceeding. Proceeding with unresolved ambiguity is a failure of integrity.
+
+Present the options clearly:
+> "I see two ways to read this:
+> 1. [Interpretation A] — my recommendation because [reason]
+> 2. [Interpretation B]
+> Which is closer to what you mean?"
+
+### 3. Surface hidden assumptions
+
+Once the user has answered the main questions, probe for assumptions:
+- "You mentioned X — does that mean Y is also true?"
+- "What happens when Z fails?"
+- "Is this for internal users, external users, or both?"
+
+### 4. Synthesize and confirm
+
+Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](../../docs/countable-story-format.md):
+- The problem (feeds into §1 Business narrative)
+- The solution and main flow (feeds into §5)
+- The key constraints and alternative flows (feeds into §6)
+- The success criteria (feeds into §17 Gherkin)
+- What's out of scope (feeds into §18)
+
+Ask: "Is this an accurate summary? Anything missing or wrong?"
+
+### 5. Write specs/planning-context.yaml
+
+After the user confirms the summary in step 4, persist the key decisions:
+
+```yaml
+# specs/planning-context.yaml — written by elaborate-spec; consumed by scope-work and slice-tasks
+feature_name: "<from step 1>"
+problem_statement: "<one paragraph>"
+constraints:
+  - "<constraint 1>"
+out_of_scope:
+  - "<excluded item 1>"
+key_decisions:
+  - decision: "<what was decided>"
+    rationale: "<why>"
+```
+
+If `specs/planning-context.yaml` already exists, ask: `"Planning context from a prior session exists. Update it? [Y/n]"`. Overwrite on Y; leave unchanged on N.
+
+### 6. Suggest next skill
+
+Once the spec is clear, recommend the next step:
+- If domain model needs work → `model-domain`
+- If ready to plan → `plan-release` (creates epic capsules with `epic.yaml` + story `.md` + `-tasks.yaml`) then `plan-work` per story
+- If a spike is needed first → `spike-prototype`
+- If architecture decisions are needed → `deepen-architecture` or `grill-me`
+- If the plan depends on a specific library or API → `grill-me` in docs mode

package/.opencode/skills/enforce-first/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: enforce-first
+model: haiku
+description: "Apply the F.I.R.S.T test quality rubric (per CONVENTIONS.md §Tests) to a test suite or individual tests. Use when develop-tdd is writing tests, when test quality needs to be checked, or when user mentions F.I.R.S.T or \"test quality\"."
+---
+
+# Enforce FIRST
+> **HARD GATE** — **HARD GATE** — Before shipping, ALL enforcement checks must pass: lint, typecheck, tests, coverage gates. Do NOT disable or skip checks to get to green.
+
+
+Apply the F.I.R.S.T rubric per CONVENTIONS.md §Tests to evaluate and improve tests.
+
+This skill is typically invoked internally by `develop-tdd` during the test-writing phase. It can also be run standalone on an existing test suite.
+
+## Modes
+
+- Default: full F.I.R.S.T audit (all 5 criteria)
+- --quick: Check Fast, Independent, and Self-Validating criteria only (per CONVENTIONS.md §Tests). Used by build-epic step 6 as a mechanical gate after audit-code. Skips Repeatable and Timely which require contextual judgment.
+
+## The F.I.R.S.T Rubric
+
+See CONVENTIONS.md §Tests for the canonical F.I.R.S.T rubric definition, checklists, and fix patterns.
+
+Mechanical self-check (runs before reporting audit complete):
+
+```bash
+grep -q '## Tests (F.I.R.S.T' CONVENTIONS.md
+grep -qE 'Fast|Independent|Repeatable|Self-Validating|Timely' CONVENTIONS.md
+```
+
+Each criterion must be explicitly addressed in the audit report with pass/fail per test file reviewed.
+
+## Applying the rubric
+
+For each failing criterion:
+1. Identify which tests violate it
+2. Describe the fix
+3. Apply the fix
+4. Re-run the suite to confirm it still passes
+
+Report: "F.I.R.S.T audit complete. X criteria passed, Y fixed."
+
+## Verify
+
+→ verify: `grep -q '## Tests (F.I.R.S.T' CONVENTIONS.md && grep -qE 'Self-Validating|Repeatable' skills/enforce-first/SKILL.md && echo OK`

package/.opencode/skills/evolve-skill/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: evolve-skill
+model: opus
+description: "Benchmark-gated skill evolution — consume bigpowers-benchmark report, propose plan-work change, edit skill via craft-skill, re-run benchmark, record ADR. Use when a skill underperforms on benchmark or stocktake finds systemic gap."
+---
+
+# story: e23s03
+
+# story: e09s01
+# story: e09s05
+
+# Evolve Skill
+
+> **HARD GATE** — No skill change ships without benchmark score ≥ pre-change baseline. Learning is measured and versioned — never implicit.
+
+## Loop
+
+1. **Regression gate** — Run `bash scripts/run-verification-gates.sh` to catch mechanical regressions (compliance, sync pipeline, size budget) before spending time on benchmark evals. If golden suite fails, fix regressions first — they are pre-requisites for any capability improvement.
+2. **Establish baseline** — Run `run-benchmark <skill> --baseline`. If no definition exists at `specs/benchmarks/<skill>.yaml`, create one following `specs/benchmarks/SCHEMA.md` first. Save report path in `state.yaml`. If `specs/benchmarks/reports/BASELINE-<skill>.yaml` already exists, skip this step.
+
+3. **Identify gap** — Read the baseline report (`specs/benchmarks/reports/BASELINE-<skill>.yaml`). Find scenarios with `result: FAIL` or low `pass_at_k`. This is the measurable gap.
+
+4. **`plan-work`** — Write a minimal change proposal targeting the failing scenarios. Include verify commands.
+
+5. **Edit** via `craft-skill` / direct SKILL.md edit; run `bash scripts/sync-skills.sh`.
+
+6. **Re-run benchmark** — `run-benchmark <skill>`. Compare new `pass_at_k` against baseline.
+   - **IMPROVED or STABLE** → advance to step 6.
+   - **REGRESSION** (`new pass_at_k < baseline`) → revert the change and loop back to step 3.
+
+7. **Record decision** — Write `specs/adr/NNNN-evolve-<skill>.md` with before/after `pass_at_k` scores. Update `session-state`.
+
+## Verify
+
+→ verify: `test -d specs/benchmarks && test -f skills/run-benchmark/SKILL.md`
+
+See [REFERENCE.md](REFERENCE.md) for ADR template.
+
+
+<!-- story: e31s07 -->
+
+---
+
+# Evolve Skill — ADR snippet
+
+```markdown
+## ADR-XXXX: Evolve &lt;skill-name&gt;
+
+**Status:** Accepted
+**Benchmark:** before X% / after Y%
+**Change:** one-sentence summary
+**Evidence:** path/to/benchmark-report.md
+```
+
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine; clone it from wherever your fork lives if absent. Never assume a hard-coded absolute path or a specific owner.

package/.opencode/skills/execute-plan/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: execute-plan
+model: haiku
+description: "Batch-execute tasks from the active epic capsule sequentially, with a human checkpoint after each step. Use when user has an approved plan and wants step-by-step oversight."
+---
+
+# Execute Plan
+
+Execute tasks from the **active epic** (`specs/epics/eNN-slug/epic.yaml` story `tasks[]`) one at a time, showing evidence after each step before proceeding.
+
+> **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first.
+>
+> **HARD GATE** — Active epic must exist with runnable `verify` on each task. If missing, run `plan-release` then `plan-work` or `build-epic`.
+
+## Process
+
+### 1. Read the plan
+
+Read `specs/state.yaml` (`active_epic`, `active_story`) and the matching `specs/epics/*/epic.yaml`. Parse `depends-on` in task descriptions for execution waves.
+
+> **CONTEXT ISOLATION** — Spawn each skill with a **fresh context window**. Pass decisions only through `specs/state.yaml` `handoff` — never rely on prior chat history.
+
+Confirm with the user: step count, skip/reorder, stop-after step.
+
+### 2. Execute step by step
+
+For each task in the active story:
+
+**a. Announce** — task `desc` and `verify` command.
+
+**b. Execute** — code or `delegate-task` / `dispatch-agents` for waves.
+
+**c. Run verify** — must be green before advancing.
+
+**d. Log** — non-obvious decisions in `specs/state.yaml` under `decisions[]` or `handoff` block.
+
+**e. Checkpoint** — ask to proceed unless autonomous mode requested.
+
+**f. Story UAT** — after last task, run manual verification script from story notes or `verify-work`.
+
+On verify failure: fix and re-run; never advance on red.
+
+Update `specs/execution-status.yaml` when a story/epic completes (`bash scripts/sync-status-from-epics.sh` or direct edit).
+
+### 3. Blockers
+
+Report blocker; ask skip/adapt/stop; update epic capsule if plan changes.
+
+### 4. Final report
+
+Suggest: `verify-work` → `run-evals` → `audit-code` → `simulate-agents` → `commit-message` → `release-branch`
+
+## Rules
+
+- **Loop until behavioral correctness is verified**: if a verify command passes but the observed behavior is still wrong, return to step 1 and run the execution cycle again.
+
+
+
+<!-- story: e02s03 -->
+<!-- story: e05s02 -->
+<!-- story: e08s01 -->

package/.opencode/skills/extract-design/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: extract-design
+model: sonnet
+description: "Extract a Google DESIGN.md file from an HTML prototype (claude.ai/design or any styled page) using Puppeteer, producing machine-readable tokens and AI-generated prose. Use when the user has an HTML prototype and wants a DESIGN.md to anchor their project's visual identity, or when seed-conventions has just scaffolded a new project."
+---
+
+# Extract DESIGN.md from HTML
+
+> **HARD GATE** — Do NOT write DESIGN.md without Puppeteer dual-pass extraction. Tokens from static HTML (Cheerio, regex, string scanning) are invalid — they miss cascade, custom properties, and Tailwind resolution.
+>
+> **HARD GATE** — Do NOT claim certainty where evidence is thin. Low-confidence color roles, component classifications, and prose assertions MUST be flagged with `<!-- AGENT NOTE: uncertain — validate during grill-me. Evidence: [what was observed] -->`.
+>
+> **HARD GATE** — Do NOT ship DESIGN.md without running `npx @google/design.md lint`. Unvalidated output is unverified output. If lint is unavailable (offline), flag prominently in terminal and in DESIGN.md prose.
+
+## Quick Start
+
+```bash
+# First run — extract from HTML prototype
+node extract-design/scripts/extract.js --source ./prototype.html
+
+# From a published URL
+node extract-design/scripts/extract.js --source https://my-prototype.example.com
+
+# With a custom name
+node extract-design/scripts/extract.js --source ./proto.html --name "My Design System"
+
+# Update — re-extract from new HTML, diff against existing
+node extract-design/scripts/extract.js --source ./proto-v2.html
+
+# Lint-only — validate existing DESIGN.md without re-extraction
+node extract-design/scripts/extract.js --lint-only
+```
+
+## Flow
+
+1. **Launch Puppeteer** — dual-pass (light + dark) with retry + timeout. CI flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`.
+2. **Collect styles** — `page.evaluate()` collects computed styles from every element. Returns raw JSON to Node.js. Browser = sensor; Node = brain.
+3. **Classify tokens** — modular pipeline: colors (Material 3 roles), typography (scale detection), spacing (tolerance GCD), rounded (clustering), components (visual signature + pseudo-state variants).
+4. **Generate prose** — AI heuristics produce all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with agent notes.
+5. **Write + validate** — serialize to `specs/tech-architecture/DESIGN_LATEST.md`, run `npx @google/design.md lint`, report to terminal.
+6. **Handoff** — writes `handoff.next_skill: grill-me` to `specs/state.yaml` with uncertain decisions context.
+
+## Inputs
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--source <file\|url>` | First run: yes. Update: optional | HTML prototype path or URL |
+| `--name <string>` | No | Design system name (defaults to `<title>` or directory name) |
+| `--lint-only` | No | Validate existing DESIGN.md without re-extraction |
+
+## Output
+
+- `specs/tech-architecture/DESIGN_LATEST.md` — replaces `DESIGN_PLAN_LATEST.md` as the canonical design artifact
+- Terminal summary: token counts, component count, lint result, uncertain decisions
+- Structured JSON log to stderr: extraction events, timing, counts
+- `specs/state.yaml` → `handoff.next_skill: grill-me` with context
+
+## Error Tiers
+
+| Tier | Condition | Response |
+|------|-----------|----------|
+| Fatal | No Chrome, page load timeout after retries | Exit non-zero, suggest fixes |
+| Degraded | Zero colors, zero typography, SPA shell | Write DESIGN.md with degradation warning |
+| Warned | Lint errors, uncertain decisions | Write DESIGN.md, flag in terminal, hand off to grill-me |
+
+## Dependencies
+
+- **Puppeteer** (Chrome binary) — wrapped behind `BrowserExtractor` interface for testability
+- **`@google/design.md`** (soft, via `npx`) — wrapped behind `DesignValidator` interface. Warns and skips if offline.
+
+## verify
+
+```bash
+node extract-design/tests/test-extraction.js
+```
+
+See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics.
+
+---
+
+# Extract Design — Reference
+
+## Extraction Algorithms
+
+### Color Classification
+1. Collect unique computed `background-color`, `color`, `border-color` from every DOM element.
+2. Count frequency and context (text vs. bg vs. border vs. button).
+3. Classify using Material 3 roles: surface = largest-area bg, on-surface = most-used text, tertiary = highest-saturation on CTAs, error = reddish.
+4. Surface container levels: luminance-ordered. Hard-cap at 3 unless data supports 5.
+5. Low-confidence → `<!-- AGENT NOTE -->` in Colors prose.
+
+### Typography Classification
+1. Collect unique (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing) tuples.
+2. Cluster by fontSize (±2px) → type scale.
+3. Detect heading hierarchy from HTML tag + computed size.
+4. Name levels: display-lg, headline-lg/md/sm, title-lg, body-lg/md/sm, label-lg/md/sm.
+5. Parse `<link>` and `@font-face`; warn if computed font differs from declared.
+
+### Spacing Classification
+1. Collect unique padding, margin, gap values. Filter: ignore values < 3 occurrences.
+2. Compute tolerance-based GCD (0.5px tolerance).
+3. Declare base unit. Detect half-step if gcd/2 values present ≥3 times.
+4. Map: unit×1 → sm, ×2 → md, ×4 → lg, ×8 → xl.
+
+### Rounded Classification
+1. Collect unique border-radius values. Cluster (1px tolerance).
+2. Name: none (0), sm (smallest), md (median), lg (large), xl (largest), full (9999px).
+
+### Component Detection
+- Button: w<300px, h<64px, bg+radius set, short text. cursor:pointer is bonus.
+- Card: bg+radius+padding set, larger area.
+- Input: `<input>` or `<textarea>` tag.
+- Pseudo-state variants: force :hover, :active, :focus for high-confidence components.
+
+### Prose Generation
+Generates all 8 DESIGN.md sections. Overview and Do's/Don'ts flagged with `<!-- AGENT NOTE: Generated from visual analysis. Grill-me should validate. -->`.
+
+## Material 3 Token Conventions
+Colors: primary, on-primary, secondary, tertiary, error, surface, on-surface, surface-container-*, outline, background, on-background.
+Typography: display-lg/md/sm, headline-lg/md/sm, title-lg/md/sm, body-lg/md/sm, label-lg/md/sm.
+Rounded: none, xs, sm, md, lg, xl, full.
+
+## CI Compatibility
+Chrome flags: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`
+
+## Defensive Code
+Retry with backoff (3 attempts, 1s/2s/4s), Timeout (30s page load, 10s pseudo-state), Graceful degradation (Tier 2 on empty extraction).
+
+## Known Risks
+- DESIGN.md spec is alpha. Skill pins to current spec.
+- Puppeteer is heavy (~300MB Chrome). Document requirement clearly.
+- Prose quality depends on AI heuristics. grill-me is the validation gate.

package/.opencode/skills/find-way/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: find-way
+model: sonnet
+description: "Plan a large effort as a shared map of decision tickets on an issue tracker, resolving them one at a time until the way is clear. Use when an idea is too big for one session, needs structured exploration before implementation, or requires mapping decisions before building."
+---
+
+# Find Way
+
+## Concept
+
+A large effort arrives — too big for one session, wrapped in fog. **Find-way** charts the way as a **shared map** on the repo's issue tracker, then works **decision tickets** — questions whose resolution is a decision, not build slices — one at a time until the route is clear.
+
+**Plan, don't do.** Each ticket resolves a decision. The map is done when the way is clear — nothing left to decide before someone executes.
+
+**Refer by name.** Every map and ticket is an issue with a title. Always use the name, never bare ids or numbers.
+
+## The Map
+
+A single issue labelled `wayfinder:map` — the canonical artifact. Child issues are its tickets.
+
+```markdown
+## Destination
+<what reaching the end looks like — one or two lines>
+
+## Notes
+<domain, skills to consult, standing preferences>
+
+## Decisions so far
+- [closed ticket title](link) — one-line gist
+
+## Not yet specified
+<in-scope fog you can't ticket yet>
+
+## Out of scope
+<work ruled beyond the destination>
+```
+
+## Ticket Types
+
+| Type | Label | Mode | Purpose |
+|------|-------|------|---------|
+| Research | `wayfinder:research` | AFK | Surface facts from docs/APIs |
+| Prototype | `wayfinder:prototype` | HITL | Cheap artifact to react to |
+| Grilling | `wayfinder:grilling` | HITL | One-question-at-a-time dialogue |
+| Task | `wayfinder:task` | Either | Manual work unblocking a decision |
+
+**HITL** = human in the loop. **AFK** = agent alone.
+
+## Two Modes
+
+### Chart the Map
+
+User invokes with a loose idea.
+
+1. **Name the destination** — grill to pin down what this map finds its way to
+2. **Map the frontier** — breadth-first: surface open decisions and first steps. If no fog emerges, the effort fits one session — skip the map
+3. **Create the map** issue (label `wayfinder:map`)
+4. **Create tickets** as child issues, then wire blocking edges in a second pass
+5. **Fire research subagents** for each `research` ticket in parallel
+6. Stop — charting resolves nothing
+
+### Work Through the Map
+
+User invokes with a map (URL/number). Ticket optional — without one, pick the next frontier ticket.
+
+1. Load the map (low-res view)
+2. **Choose & claim** — assign ticket before any work
+3. **Resolve** — zoom into related/closed tickets as needed
+4. **Record** — post resolution comment, close issue, append to Decisions-so-far
+5. **Graduate fog** — create new tickets from newly-specifiable fog, clear from Not-yet-specified
+6. **Rule out of scope** if resolution reveals something past the destination
+
+**Never resolve more than one ticket per session** (except research).
+
+## Fog of War
+
+Beyond live tickets lies the **fog** — decisions you can tell are coming but can't pin down yet. The **Not yet specified** section holds this dim view.
+
+**Fog or ticket?** Test: can you state the question precisely now?
+
+- **Ticket** when the question is sharp (even if blocked)
+- **Not yet specified** when you can't phrase it sharply yet
+
+## Out of Scope
+
+Work beyond the destination. Ruling something out is a scoping act, not a route step. Never graduates — returns only if destination is redrawn.
+
+If an existing ticket sits past the destination, close it and note in Out of scope.
+
+## Blocking & Frontier
+
+- **Blocking**: tracker's native dependency relationship
+- **Unblocked**: every blocker is closed
+- **Frontier**: open, unblocked, unclaimed children — the edge of the known
+
+## Detailed Reference
+
+See [REFERENCE.md](REFERENCE.md) for ticket anatomy, resolution protocol, and examples.
+
+---
+
+# Find-Way Reference
+
+## Ticket Anatomy
+
+Each ticket holds one question, sized to one 100K token agent session:
+
+```markdown
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+**Labels:** `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`
+
+**Claim:** Assign to yourself before any work — claim blocks concurrent sessions.
+
+**Blocking:** Use tracker's native dependency relationship so the frontier renders visually.
+
+**Resolution:** Post answer as a comment, close the issue, append to map's Decisions-so-far.
+
+## Resolution Protocol
+
+1. **Load the map** — read low-res view, not every ticket body
+2. **Choose & claim** — assign ticket to yourself (or take first frontier ticket if not named)
+3. **Resolve** — zoom into related/closed tickets as needed; invoke skills the Notes block names
+4. **Record** — post resolution comment with the answer, close the issue
+5. **Update map** — append to Decisions-so-far with one-line gist + link
+6. **Graduate fog** — create new tickets from newly-specifiable fog; clear from Not-yet-specified
+7. **Rule out of scope** if resolution reveals something past the destination
+
+## Ticket Types in Detail
+
+### Research (AFK)
+Surfacing facts from docs, APIs, or knowledge bases that a decision waits on.
+- Resolved by a `/research` subagent
+- Use when knowledge outside the working directory is required
+- **Label:** `wayfinder:research`
+
+### Prototype (HITL)
+Raise fidelity by building cheap, rough, concrete artifact to react to — outline, stub, UI/logic code.
+- Use the `/prototype` skill
+- Links the prototype as an asset
+- Use when "how should it look" or "how should it behave" is key
+- **Label:** `wayfinder:prototype`
+
+### Grilling (HITL)
+Conversation via `/grilling` and `/domain-modeling` skills, one question at a time.
+- The default case for clarifying decisions
+- **Label:** `wayfinder:grilling`
+
+### Task (HITL or AFK)
+Manual work unblocking a decision — signing up for service, provisioning access, moving data.
+- This is the **only** type that does rather than decides
+- Earns its place by unblocking a decision, not by delivering the destination
+- Agent drives AFK tasks alone; HITL tasks get precise checklist
+- **Label:** `wayfinder:task`
+
+## Fog-to-Ticket Graduation
+
+When resolving a ticket clears fog, graduate the newly-specifiable bits into fresh tickets:
+
+1. **Identify the fog** in Not-yet-specified that the resolution illuminates
+2. **Create new tickets** with crisp question statements
+3. **Wire blocking edges** if the new tickets depend on each other or existing ones
+4. **Clear from fog** — remove the graduated patch from Not-yet-specified so it lives only as its ticket
+
+## Out-of-Scope Close Protocol
+
+If a ticket turns out to sit past the destination:
+
+1. **Close the ticket** — mark it resolved or won't-fix
+2. **Add one line to Out of scope** — gist + why it's out of scope, linking the closed ticket
+3. **Never append to Decisions so far** — scope boundaries aren't steps on the route
+
+## Map State Transitions
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| **Open, unblocked, unclaimed** | Frontier — ready to take | Claim and resolve |
+| **Open, blocked** | Waiting on something | Wait for blockers to close |
+| **Open, claimed** | Concurrent session working | Skip for now |
+| **Closed** | Decided — lives in Decisions so far | Reference, don't re-open |
+
+## Concurrency
+
+Users may run unblocked tickets in parallel, so expect the tracker to be edited concurrently. Always:
+
+- Refresh the map before picking a ticket
+- Claim immediately before starting work
+- Never assume state hasn't changed since last read

package/.opencode/skills/fix-bug/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: fix-bug
+model: sonnet
+description: "Bug fix orchestrator — active_flow fix_bug; reads specs/bugs/BUG-*.md; chains investigate-bug, develop-tdd, validate-fix. Use when user reports a defect."
+---
+
+# Fix Bug
+
+**Boundary**: Orchestrator flow — chains `investigate-bug` (entry point + RCA via `diagnose-root`) → `develop-tdd` → `validate-fix`. Does not implement RCA or write bug files directly.
+
+Orchestrates **fix_bug** flow without mixing epic build state.
+
+> **HARD GATE** — Set `specs/state.yaml` `active_flow: fix_bug` and `bug_cycle.current_step: 1` before starting.
+
+## Discovered gate failures (e51s04)
+
+Valid entry **without a user-reported bug** when:
+
+- **Preflight** or **CI** is red at kickoff or verify-work
+- **Golden suite** or project baseline is red (`bash scripts/run-verification-gates.sh` or equivalent)
+- A reproducible gate failure during unrelated epic work exceeds quick-fix guardrails
+
+Create `specs/bugs/BUG-*.md` via `investigate-bug` (or inline in fix-bug step 1) describing the gate failure, then run the standard fix_bug chain.
+
+## Five steps (`bug_cycle` in state.yaml)
+
+| Step | Skill / action |
+|------|----------------|
+| 1 | `investigate-bug` — create BUG-*.md with RCA |
+| 2 | `diagnose-root` — 4-phase root cause analysis |
+| 3 | `develop-tdd` — red-green against bug file verify steps |
+| 4 | `validate-fix` — re-run failing test, full suite, lint |
+| 5 | `release-branch` — PR or solo land the fix |
+
+### Checkpoint / resume
+
+Track progress via `specs/state.yaml` `bug_cycle`:
+- `bug_cycle.current_step`: current step (1–5)
+- `bug_cycle.completed_steps`: completed step numbers
+- `handoff.next_skill`: skill for the current step
+- On resume, read `bug_cycle.current_step` and continue from there
+
+## Process
+
+1. **Step 1 — investigate-bug:** If no `specs/bugs/BUG-*.md`, run `investigate-bug` first — it handles history check, RCA (via `diagnose-root`), fix approach, and writes the bug file. Increment `bug_cycle.current_step` to 2 on completion.
+2. **Step 2 — diagnose-root:** Run 4-phase RCA (reproduce → isolate → hypothesize → verify). Record findings in the bug file. Increment to step 3.
+3. **Step 3 — develop-tdd:** `develop-tdd` against the bug file's verify steps. Increment to step 4 on all-green.
+4. **Step 4 — validate-fix:** `validate-fix` — re-run failing test, full suite, typecheck, lint. Increment to step 5.
+5. **Step 5 — release-branch:** Land the fix via `release-branch`. Clear `bug_cycle` and `active_flow` when done.
+
+## Bug file SoT
+
+One markdown file per bug with frontmatter:
+
+```yaml
+---
+bug_id: BUG-001
+status: open
+severity: high
+scope: api
+title: Short title
+---
+```
+
+## Verify
+
+→ verify: `test -d specs/bugs && test -f scripts/run-skill-verify.sh`