@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/skills/memory-flush/tests/run.sh

@@ -0,0 +1,327 @@
+#!/usr/bin/env bash
+# Fixture-based integration tests for the memory-flush Step 0 SOP.
+# Covers AC-001, AC-002, AC-004, AC-006 from docs/specs/memory-lifecycle-closure.md
+#
+# The SKILL.md SOP is markdown; the executable contract lives in
+# `.claude/skills/memory-flush/sweep.py`, a deterministic helper the SOP
+# invokes for the sweep-and-classify portion of Step 0. Each test builds a
+# stubbed memory tree, invokes sweep.py with a stubbed reply stream, and
+# asserts on the resulting file state + JSON action report.
+#
+# Until sweep.py exists, every flush test fails RED (correct TDD state).
+# AC-006 regression-traps stay green from day one and must stay green.
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$HERE/../../../.." && pwd)"
+SWEEP="$REPO_ROOT/.claude/skills/memory-flush/sweep.py"
+
+PASS=0; FAIL=0; FAILED=()
+
+# --- assertion helpers --------------------------------------------------------
+
+fail() { echo "  FAIL: $*"; return 1; }
+
+assert_file_contains() {
+  local path="$1" needle="$2" msg="$3"
+  if grep -qF "$needle" "$path" 2>/dev/null; then return 0; fi
+  fail "$msg :: file $path missing: $needle"
+}
+
+assert_file_not_contains() {
+  local path="$1" needle="$2" msg="$3"
+  if grep -qF "$needle" "$path" 2>/dev/null; then
+    fail "$msg :: file $path should NOT contain: $needle"
+    return 1
+  fi
+}
+
+assert_contains() {
+  local haystack="$1" needle="$2" msg="$3"
+  case "$haystack" in
+    *"$needle"*) return 0 ;;
+    *) fail "$msg :: expected to contain: $needle" ;;
+  esac
+}
+
+# Invoke sweep.py against a fixture memory dir.
+#   $1 = mode (auto-close | prose-scan | stale-sweep)
+#   $2 = memory dir
+#   $3 = reply stream (newline-separated; piped to stdin)
+# Stdout = JSON report from sweep.py; exit 0 success, non-zero error.
+sweep() {
+  local mode="$1" mem="$2" replies="${3:-}"
+  if [ ! -x "$SWEEP" ] && [ ! -f "$SWEEP" ]; then
+    echo "{\"error\":\"sweep.py missing\"}"
+    return 127
+  fi
+  printf '%s' "$replies" | python3 "$SWEEP" --mode "$mode" --memory-dir "$mem"
+}
+
+seed_skel() {
+  local mem="$1"
+  mkdir -p "$mem"
+  for f in landmarks libraries decisions landmines conventions pending-questions; do
+    cat > "$mem/$f.md" <<EOF
+---
+owners: [test]
+size-cap: 500
+key: test
+---
+
+# Fixture
+EOF
+  done
+}
+
+# Append an entry block to a canonical file.
+add() {
+  local mem="$1" file="$2"; shift 2
+  printf '\n%s\n' "$*" >> "$mem/$file.md"
+}
+
+days_ago() {
+  local n="$1"
+  if date -u -d "$n days ago" +%Y-%m-%d 2>/dev/null; then return; fi
+  date -u -v "-${n}d" +%Y-%m-%d
+}
+
+today() { date -u +%Y-%m-%d; }
+
+run() {
+  local name="$1"
+  echo "RUN  $name"
+  if "$name"; then
+    PASS=$((PASS+1)); echo "PASS $name"
+  else
+    FAIL=$((FAIL+1)); FAILED+=("$name"); echo "FAIL $name"
+  fi
+}
+
+# --- AC-001 -------------------------------------------------------------------
+
+test_when_resolved_at_present_on_pending_then_flush_removes_block() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-100
+
+- Question: stub
+- verified-at: HEAD
+- last-touched: $(today)
+- resolved-at: 2026-05-01"
+  local report; report="$(sweep auto-close "$mem")" || { fail "AC-001 sweep crashed"; return 1; }
+  assert_file_not_contains "$mem/pending-questions.md" "## Q-100" "AC-001 expected Q-100 block removed" || return 1
+  assert_contains "$report" '"closed": 1' "AC-001 expected closed count 1 in report (got: $report)" || return 1
+}
+
+test_when_superseded_at_present_on_landmarks_then_flush_removes_block() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "landmarks" "## src/old.js:42
+
+- role: legacy entrypoint
+- verified-at: HEAD
+- last-touched: $(today)
+- superseded-at: 2026-05-01"
+  local report; report="$(sweep auto-close "$mem")" || { fail "AC-001 sweep crashed"; return 1; }
+  assert_file_not_contains "$mem/landmarks.md" "## src/old.js:42" "AC-001 expected superseded block removed" || return 1
+  assert_contains "$report" '"closed": 1' "AC-001 expected closed count 1 in report" || return 1
+}
+
+test_when_resolved_at_malformed_then_entry_remains_open() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-200
+
+- Question: stub
+- verified-at: HEAD
+- last-touched: $(today)
+- resolved-at: 2026-13-99"
+  local report; report="$(sweep auto-close "$mem")" || { fail "AC-001 sweep crashed on malformed"; return 1; }
+  assert_file_contains "$mem/pending-questions.md" "## Q-200" "AC-001 malformed date must NOT delete entry" || return 1
+  assert_contains "$report" '"malformed":' "AC-001 expected malformed flag in report" || return 1
+}
+
+test_when_resolved_at_on_wrong_file_then_skill_flags_violation() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  # resolved-at on landmarks.md is a per-file invariant violation.
+  add "$mem" "landmarks" "## src/x.js:1
+
+- role: test
+- verified-at: HEAD
+- last-touched: $(today)
+- resolved-at: 2026-05-01"
+  local report; report="$(sweep auto-close "$mem")" || { fail "AC-001 sweep crashed"; return 1; }
+  assert_file_contains "$mem/landmarks.md" "## src/x.js:1" "AC-001 invariant-violation entry must NOT be deleted" || return 1
+  assert_contains "$report" '"invariant_violation":' "AC-001 expected invariant_violation flag in report" || return 1
+}
+
+# --- AC-002 -------------------------------------------------------------------
+
+test_when_pending_entry_has_resolution_prose_and_y_then_block_removed() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-300
+
+- Question: stub
+**Resolution path taken (2026-04-29):** decided in spec.
+- verified-at: HEAD
+- last-touched: $(today)"
+  # Reply stream: 'y' to confirm removal.
+  local report; report="$(sweep prose-scan "$mem" "y")" || { fail "AC-002 sweep crashed"; return 1; }
+  assert_file_not_contains "$mem/pending-questions.md" "## Q-300" "AC-002 'y' must delete block" || return 1
+  assert_contains "$report" '"closed_by_confirm": 1' "AC-002 expected closed_by_confirm 1 (got: $report)" || return 1
+
+  # 'n' keeps the entry.
+  rm -rf "$mem"; mem="$(mktemp -d)"; seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-301
+
+- Question: stub
+**Resolution path taken (2026-04-29):** decided in spec.
+- verified-at: HEAD
+- last-touched: $(today)"
+  sweep prose-scan "$mem" "n" >/dev/null || { fail "AC-002 sweep crashed on 'n'"; return 1; }
+  assert_file_contains "$mem/pending-questions.md" "## Q-301" "AC-002 'n' must keep block" || return 1
+
+  # 'skip' keeps the entry and marks for next-run reconsideration.
+  rm -rf "$mem"; mem="$(mktemp -d)"; seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-302
+
+- Question: stub
+**Resolution path taken (2026-04-29):** decided.
+- verified-at: HEAD
+- last-touched: $(today)"
+  report="$(sweep prose-scan "$mem" "skip")"
+  assert_file_contains "$mem/pending-questions.md" "## Q-302" "AC-002 'skip' must keep block" || return 1
+  assert_contains "$report" '"deferred":' "AC-002 'skip' should produce deferred marker" || return 1
+}
+
+test_when_body_has_resolved_by_alice_anchored_then_surfaced() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-310
+
+- Question: who decides
+Resolved by Alice 2026-05-01
+- verified-at: HEAD
+- last-touched: $(today)"
+  local report; report="$(sweep prose-scan "$mem" "y")" || { fail "AC-002 sweep crashed"; return 1; }
+  assert_file_not_contains "$mem/pending-questions.md" "## Q-310" "AC-002 R3 anchored should surface and delete on 'y'" || return 1
+  assert_contains "$report" '"closed_by_confirm": 1' "AC-002 expected closed_by_confirm 1" || return 1
+}
+
+test_when_body_has_resolved_midsentence_then_not_surfaced() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-320
+
+- Question: we resolved most of this last week but still need a date.
+- verified-at: HEAD
+- last-touched: $(today)"
+  # No replies; if a prompt surfaces unexpectedly the sweep will hang or pick a default.
+  local report; report="$(sweep prose-scan "$mem" "")" || { fail "AC-002 sweep crashed"; return 1; }
+  assert_file_contains "$mem/pending-questions.md" "## Q-320" "AC-002 mid-sentence must NOT surface" || return 1
+  assert_contains "$report" '"surfaced": 0' "AC-002 expected surfaced 0 for mid-sentence (got: $report)" || return 1
+}
+
+# --- AC-004 -------------------------------------------------------------------
+
+test_when_2_stale_then_flush_offers_reverify_then_delete_prompts() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "landmarks" "## src/keep.js:1
+
+- role: test
+- verified-at: HEAD
+- last-touched: $(days_ago 120)"
+  add "$mem" "landmarks" "## src/drop.js:1
+
+- role: test
+- verified-at: HEAD
+- last-touched: $(days_ago 130)"
+  # Replies: re-verify (keep+restamp) then delete.
+  local report; report="$(sweep stale-sweep "$mem" "re-verify
+delete")" || { fail "AC-004 sweep crashed"; return 1; }
+  # First entry kept with refreshed last-touched.
+  assert_file_contains "$mem/landmarks.md" "## src/keep.js:1" "AC-004 reverify must keep" || return 1
+  assert_file_contains "$mem/landmarks.md" "last-touched: $(today)" "AC-004 reverify must restamp last-touched" || return 1
+  # Second entry deleted.
+  assert_file_not_contains "$mem/landmarks.md" "## src/drop.js:1" "AC-004 delete must remove" || return 1
+  assert_contains "$report" '"reverified": 1' "AC-004 expected reverified 1" || return 1
+  assert_contains "$report" '"deleted": 1' "AC-004 expected deleted 1" || return 1
+}
+
+test_when_stale_mark_closed_on_pending_then_resolved_at_added_not_deleted() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "pending-questions" "## Q-400
+
+- Question: stub
+- verified-at: HEAD
+- last-touched: $(days_ago 120)"
+  sweep stale-sweep "$mem" "mark-closed" >/dev/null || { fail "AC-004 sweep crashed"; return 1; }
+  assert_file_contains "$mem/pending-questions.md" "## Q-400" "AC-004 mark-closed must NOT delete this run" || return 1
+  assert_file_contains "$mem/pending-questions.md" "resolved-at:" "AC-004 mark-closed must add resolved-at on pending-questions" || return 1
+}
+
+# --- AC-006 (regression traps — start green, stay green) ----------------------
+
+test_when_no_closure_no_prose_no_stale_then_entry_survives_all_paths() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  add "$mem" "landmarks" "## src/normal.js:1
+
+- role: ordinary entry, no closure, no prose match
+- verified-at: HEAD
+- last-touched: $(today)"
+  local before; before="$(cat "$mem/landmarks.md")"
+  # Step 0a auto-close.
+  sweep auto-close "$mem" >/dev/null
+  # Step 0b prose-scan with no replies (nothing should be surfaced).
+  sweep prose-scan "$mem" "" >/dev/null
+  # Step 0c stale-sweep (entry is not stale; nothing to do).
+  sweep stale-sweep "$mem" "" >/dev/null
+  local after; after="$(cat "$mem/landmarks.md")"
+  if [ "$before" = "$after" ]; then return 0; fi
+  fail "AC-006 entry mutated through Step 0 a/b/c"
+  diff <(printf '%s' "$before") <(printf '%s' "$after") || true
+  return 1
+}
+
+test_when_pre_spec_entry_no_source_no_verbatim_then_grandfathered() {
+  local mem; mem="$(mktemp -d)"; trap "rm -rf $mem" RETURN
+  seed_skel "$mem"
+  # Legacy shape: no `source:`, no `verbatim:` block.
+  add "$mem" "conventions" "## legacy-entry
+
+- pattern: legacy
+- verified-at: HEAD
+- last-touched: $(today)"
+  sweep auto-close "$mem" >/dev/null || { fail "AC-006 sweep crashed"; return 1; }
+  sweep prose-scan "$mem" "" >/dev/null
+  assert_file_contains "$mem/conventions.md" "## legacy-entry" "AC-006 grandfathered legacy entry survives" || return 1
+}
+
+# --- runner -------------------------------------------------------------------
+
+run test_when_resolved_at_present_on_pending_then_flush_removes_block
+run test_when_superseded_at_present_on_landmarks_then_flush_removes_block
+run test_when_resolved_at_malformed_then_entry_remains_open
+run test_when_resolved_at_on_wrong_file_then_skill_flags_violation
+run test_when_pending_entry_has_resolution_prose_and_y_then_block_removed
+run test_when_body_has_resolved_by_alice_anchored_then_surfaced
+run test_when_body_has_resolved_midsentence_then_not_surfaced
+run test_when_2_stale_then_flush_offers_reverify_then_delete_prompts
+run test_when_stale_mark_closed_on_pending_then_resolved_at_added_not_deleted
+run test_when_no_closure_no_prose_no_stale_then_entry_survives_all_paths
+run test_when_pre_spec_entry_no_source_no_verbatim_then_grandfathered
+
+echo "----"
+echo "Passed: $PASS  Failed: $FAIL"
+if [ "$FAIL" -gt 0 ]; then
+  echo "Failed tests:"
+  for t in "${FAILED[@]}"; do echo "  - $t"; done
+fi
+exit $((FAIL > 0))

package/obj/template/.claude/skills/prose/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: prose
+owner: baseline
+description: Draft or revise English prose for any brief — documentation body, intake problem statements, spec context, RCA summaries, marketing copy, README sections, PR descriptions. Mandatorily invokes `Skill(humanizer)` as the final pass on every draft. Conditionally invokes `copywriting` for persuasive register, `documentation` for reference docs, `technical-tutorials` for tutorials. Used when any phase needs human-readable prose written or rewritten. Composition only — research and register-picking happen in the caller's context.
+---
+
+You are executing a **decision the main context has already made**: "produce this specific prose, for this audience, in this register, grounded in this source material." You compose. You do not invent facts, pick the register, or expand scope.
+
+# The skill is invalid without an explicit `Skill(humanizer)` tool call
+
+This is the load-bearing rule. The other rules support it.
+
+- Every prose deliverable produced by this skill must end with the model issuing a `Skill(humanizer)` tool call against the draft, and using humanizer's output **verbatim** as the final text.
+- Reading humanizer's patterns from memory and rewriting "in humanizer's spirit" does not satisfy this rule. The Skill tool call must occur in the same turn as the prose.
+- "I know these patterns, I'll skip the call to save tokens" is the exact failure this rule prevents. Skip is forbidden even for a single sentence.
+- The receipt line at the end of your output must reference the turn-local humanizer Skill tool call. If you cannot honestly write that line, the deliverable is not done.
+
+# Before you draft — load this checklist
+
+Hold these patterns in active context for the whole drafting pass. Drafting against the checklist is cheaper than rewriting after.
+
+**Forbidden in human-facing prose:**
+
+- **Em-dash overuse.** Treat the em dash as expensive. Maximum one em dash per paragraph. Two em dashes in the same paragraph is always wrong; stacking em dashes around a parenthetical (`A — X — B`) is always wrong.
+- **Sentence-fragment stacking.** Three or more short fragments in a row read as AI rhythm. "Skills run here. One worker there. Discipline through composition." — that pattern is the tell. Vary length. Break the rhythm.
+- **Sloganeering in body copy.** "Placement is policy." "The audit is the contract." "Discipline through composition." Headline rhythms in paragraph copy are AI signatures. State the claim plainly and move on.
+- **Tagline echo.** If the headline contains a phrase, the body paragraph should not repeat that phrase. Echoing reinforces the slogan and feels engineered.
+- **Negative parallelism.** "It's not just X, it's Y." "What this is not: …. It is also not …." Cut these structures unless one specific instance is genuinely the cleanest expression.
+- **Rule of three.** Forced triplets that round out a list to three items for cadence. If you have two real items, write two.
+- **AI vocabulary.** *crucial, pivotal, leverage, robust, comprehensive, seamless, holistic, foster, navigate, journey, harness (verb), unleash, cutting-edge, game-changing, paradigm, synergy, delve, tapestry, testament, underscore, landscape (abstract), vibrant, in the heart of, nestled.*
+- **Vague attributions.** "Industry experts believe", "research suggests", "many would argue".
+- **Filler hedges.** "It is important to note that", "in order to", "at this point in time", "due to the fact that".
+- **Generic positive endings.** "Exciting times ahead." "The future looks bright." "A major step forward."
+- **Bolded inline-header lists** (`- **User Experience:** …`) and emoji decoration. Cut both.
+- **Curly quotes** (`“”` `‘’`). ASCII straight quotes only.
+
+The full pattern set with examples lives in `humanizer/SKILL.md`. The list above is the high-frequency subset; the Skill tool call below loads the full set.
+
+# Conditional skills the caller specifies
+
+Run **before** humanizer. The caller names which one applies. Do not pick more than one.
+
+- `Skill(copywriting)` — when register is persuasive (landing/pricing/feature/hero/CTA/tagline).
+- `Skill(documentation)` — when register is technical reference.
+- `Skill(technical-tutorials)` — when register is step-by-step walkthrough.
+
+# Inputs the caller must provide
+
+Stop and ask if any are unclear.
+
+- **Brief**: what to write. Length. What it's for.
+- **Source material**: facts, links, quotes, diff slices, spec excerpts. Anything you'd otherwise be tempted to invent must be in here.
+- **Audience**: internal engineer, external user, mixed.
+- **Register**: reference doc · tutorial · summary · marketing/product · PR description · runbook intro · etc. The caller picks; you execute.
+- **Output target**: a file path, a section to edit, or "return inline."
+
+# Method
+
+1. **Draft from source material only.** Vary sentence length and rhythm. Use first person when register supports it. Acknowledge complexity where real. Be specific — real numbers, real names, real behaviors.
+2. **Run the pre-draft checklist over your draft.** Read the draft once with the forbidden-pattern list active. Cut every hit before moving to step 3. This is the cheap pass; it removes 80% of what humanizer would otherwise reject.
+3. **Apply the conditional skill the caller named** via `Skill(...)`. Use its output as your working draft.
+4. **Invoke `Skill(humanizer)` with the entire working draft.** Use humanizer's output verbatim. Do not paraphrase; do not cherry-pick its suggestions. If humanizer changes something you intended to keep, you may either accept the change or invoke humanizer again with explicit guidance — you may not silently revert.
+5. **Self-audit grep the final text.** Apply these mechanical checks in your head before declaring done:
+   - Em-dash count per paragraph: 0 or 1, never 2+.
+   - Three-fragment-in-a-row patterns: count and break any you find.
+   - Slogan-in-body-paragraph patterns: any sentence under 6 words that sits alone in a paragraph and could be a headline → rewrite into the surrounding sentence.
+   - AI-vocabulary scan: re-grep the forbidden word list above. Any hit that survived humanizer → fix manually.
+   - Headline-tagline echo: search the body for any phrase repeated from the H1/H2.
+   If any check fails, fix and re-invoke `Skill(humanizer)` on the corrected draft. Do not ship a draft that fails self-audit.
+6. **Land the output** at the caller's target.
+
+# Output
+
+- **File target given** → write/edit the file.
+- **Section edit given** → edit the referenced section in place.
+- **Inline return** → put the finished prose in your response.
+
+Always close with one line stating evidence:
+
+```
+Invoked: Skill(humanizer) on the draft this turn. Conditional: <copywriting | documentation | technical-tutorials | none>. Self-audit: passed.
+```
+
+If you cannot honestly write that exact line — because you didn't issue a `Skill(humanizer)` tool call this turn, or because self-audit found a hit you didn't fix — the deliverable is not complete. Re-do the pass before returning to the caller.
+
+# Hard scope: never humanize Claude-instructional prose
+
+The humanizer pass is for prose meant for **human readers**. Some markdown files in this repo look like prose but are contracts Claude reads to decide behavior. Rewriting those for "natural rhythm" can soften imperatives, drop precision, or break load-bearing repetition.
+
+**Refuse to humanize, even on explicit caller request:**
+
+- `CLAUDE.md` — session constitution.
+- `docs/init/seed.md` — rebuild prompt.
+- `.claude/skills/*/SKILL.md` — skill prompts. Imperatives are load-bearing.
+- `.claude/agents/*.md` — subagent prompts.
+- `.claude/commands/*.md` — command prompts.
+- `.claude/skills/*/template.md` — canonical structures downstream guards check.
+- Any file whose primary reader is Claude rather than a human.
+
+Detection rule: if the file is read into Claude's context as instructions, it is **out of scope**. If unsure, ask the caller.
+
+**In scope:**
+
+- `README.md` user-facing sections (intro, quickstart, "what you get") — layout-tree and config tables stay untouched.
+- `site/**` (or whichever rendered-site path the project uses — check `project.json → workflow.artifacts.document`) — rendered site for human readers. Marketing copy inside JSX/TSX strings is in scope; surrounding code is not.
+- Intake / spec Context / RCA Summary narrative blocks — prose that conveys reasoning to a human reviewer.
+- Commit message bodies (when caller asks).
+- Onboarding / migration / how-to docs.
+
+When humanizing prose blocks inside a mostly-instructional file (e.g., the user-facing intro of `README.md`), surgically scope edits to the prose blocks. Never run a whole-file pass on a mixed file.
+
+# Constraints
+
+- **`Skill(humanizer)` is mandatory, always.** No exceptions for short, polished, or "obviously fine" passages.
+- **Don't invent facts.** If the source material doesn't support a claim, drop the claim.
+- **Match the caller's voice when specified.** A migration runbook sounds different from a hero section.
+- **Start terse.** Length bloat is a top humanizer pattern. Expand only when the brief explicitly asks for depth.
+- **Don't over-hedge.** "It could potentially possibly be the case that..." gets cut.
+- **Code and code comments are out of scope.** If the brief is "write a function" or "fix this bug", decline and route to `implement`.

package/obj/template/.claude/skills/rca/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: rca
+owner: baseline
+description: Draft a Root Cause Analysis for an incident, outage, or repeated test failure. Unlike intake/spec/brd, RCA is not a workflow phase — it's a standalone postmortem artifact that often precedes a bugfix intake. Output lives at `docs/rca/<slug>.md`.
+---
+
+# RCA — Root Cause Analysis
+
+You are drafting an **RCA**. It is a narrative of what went wrong, why, and what will change so it doesn't recur. Unlike the other artifact skills in this workflow, RCA is **not** part of the linear phase chain — it's a separate document that often feeds into a bugfix intake (`/triage` → `/intake` → …).
+
+**Use an RCA when:**
+- A production incident occurred (outage, data corruption, security breach).
+- A test that previously passed now fails intermittently and the cause is non-obvious.
+- A `verify` skill verdict has been `FAIL` across multiple attempts and the team needs a blameless record.
+- The user explicitly says "postmortem", "RCA", "incident review", or equivalent.
+
+**Don't use an RCA for:** a bug reported in a ticket, a missing feature, or a normal TDD failure. Those belong in intake/spec/tdd.
+
+## Inputs
+
+- The incident's observable facts: timeline, alerts, logs, user reports, metrics screenshots (paths or URLs).
+- The commits, deploys, or config changes in the suspect window.
+- `template.md` in this skill directory.
+
+## Steps
+
+1. Read `template.md`. Every heading must appear in the output.
+2. Assemble the **Timeline** from raw evidence (logs, alert history, chat transcripts, deploy log). Wall-clock times in a single timezone. Do NOT paraphrase events — record what happened.
+3. State the **Root cause** as a single sentence. If you have multiple candidate causes and cannot distinguish them from the evidence, list them under **Contributing factors** and put "not conclusively identified" as the Root cause. Do not guess.
+4. **Impact must be quantified.** Users affected: count or estimate with method. Duration: precise. Business impact: dollars, SLA minutes, or "none measurable" — never a vague "significant".
+5. **Action items have owners and due dates.** Unassigned action items are placeholder; delete them or assign.
+6. Write to `docs/rca/<slug>.md`. Slug: `YYYY-MM-DD-<short-name>` so the file sorts chronologically in the directory.
+7. Tell the user: "RCA drafted at `docs/rca/<slug>.md`. Action items: N, owners assigned: M. If this warrants a fix, run `/triage` with a bugfix description referencing this RCA."
+
+## Drafting rules
+
+- **Blameless.** Describe what a system or process allowed, not who is at fault. "The deploy ran without a staging rehearsal" — not "Alice deployed without testing".
+- **Evidence links trump prose.** Where possible, cite the log line, the commit SHA, the dashboard URL. Prose that isn't traceable is speculation.
+- **What went well matters.** Most RCAs omit this. Include it — it reinforces practices that should persist.
+- **Action items are specific.** "Improve monitoring" is not an action item; "Add alarm on upstream 5xx rate > 1% for 2m, paging to #oncall-payments, owner: Priya, due 2026-05-15" is.
+- **Do not self-commit to a timeline you can't honor.** If action item ETAs are uncertain, mark them "tentative".
+- **Don't mix RCA and spec.** The RCA says what broke and why. The fix spec (separate, via `/spec`) says how to repair it.

package/obj/template/.claude/skills/rca/template.md

@@ -0,0 +1,83 @@
+# RCA: <short incident name>
+
+<!--
+Root Cause Analysis. Produced by the `rca` skill.
+Required sections (enforced by artifact_template_guard): Summary, Timeline,
+Impact, Root cause, Action items.
+Blameless by convention: describe systems and processes, not individuals.
+-->
+
+## Summary
+
+<Two sentences. What broke, when, and whether it's resolved as of writing.>
+
+## Timeline
+
+<Wall-clock, one timezone (state which). Sourced from evidence. Every entry
+links to a log / alert / commit / chat where possible.>
+
+- `YYYY-MM-DD HH:MM TZ` — <event>. <link/evidence>
+- `YYYY-MM-DD HH:MM TZ` — <event>. <link/evidence>
+- `YYYY-MM-DD HH:MM TZ` — <event>. <link/evidence>
+
+## Impact
+
+<Quantified. Users affected with counting method. Duration precise.
+Business/SLA/dollar impact or "none measurable".>
+
+- **Users affected**: <count/estimate + method>
+- **Duration**: <start → end, total minutes>
+- **SLA impact**: <e.g., 23 minutes against 99.9% monthly error budget>
+- **Business impact**: <dollars, or "none measurable">
+- **Data impact**: <loss? corruption? none?>
+
+## Detection
+
+<How did we notice? Who/what raised the alarm? Was the detection time
+acceptable? What would have made detection faster?>
+
+## Root cause
+
+<Single sentence. What was the underlying condition that, removed, would
+have prevented this incident? If inconclusive, state so here and enumerate
+candidates under Contributing factors.>
+
+## Contributing factors
+
+<Conditions that worsened the incident but are not the single root cause.>
+
+- <factor>
+- <factor>
+
+## Resolution
+
+<What was done to resolve it. Commands run, configs reverted, deploys. Link
+the fix commit(s) if any.>
+
+## What went well
+
+<Behaviours/tools/practices that limited the blast radius or sped recovery.
+These should persist.>
+
+- <item>
+
+## What could be improved
+
+<Process gaps exposed by the incident.>
+
+- <item>
+
+## Action items
+
+<Each has: a description, an owner (named person), a due date (absolute,
+YYYY-MM-DD), and a status.>
+
+- [ ] **AI-01** — <description>. Owner: <name>. Due: <YYYY-MM-DD>. Status: open.
+- [ ] **AI-02** — <description>. Owner: <name>. Due: <YYYY-MM-DD>. Status: open.
+
+## Links
+
+<Incident ticket, deploy logs, dashboards, related commits, prior RCAs if
+this is a recurrence.>
+
+- <label>: <url>

package/obj/template/.claude/skills/research/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: research
+owner: baseline
+description: Workflow Phase 3 — Research and Solution Exploration. Surfaces 2–4 candidate solution approaches with concrete tradeoffs, grounded in current library docs via context7 MCP — never in training-data recall. Output lives at `docs/research/<slug>.md`. Executes in main context.
+---
+
+You are surfacing a small set of candidate approaches to a task, with honest tradeoffs, so the spec author can pick one. Decisions are not made here — the human reviewer decides at `/spec`. Your job is to lay out the option space.
+
+# Prereqs
+
+- `scout` in `completed` OR in `exceptions`.
+
+# Inputs
+
+- The intake at `docs/intake/<slug>.md` — **Constraints** and **Acceptance criteria** sections filter which approaches are viable.
+- The scout report at `docs/scout/<slug>.md` — patterns in use, touchpoints, landmines.
+- The BRD at `docs/brd/<slug>.md` if present — NFR-### requirements (latency, compliance, etc.).
+- The existing tech stack — read `package.json`, `pyproject.toml`, `go.mod`, lockfiles.
+
+# Mandatory: context7 MCP for library APIs
+
+For any library you intend to cite:
+
+1. `mcp__plugin_context7_context7__resolve-library-id`
+2. `mcp__plugin_context7_context7__query-docs`
+
+**Never cite an API from memory.** Record the version present in the lockfile and confirm the docs match that major version. If context7 has no coverage, fall back to `WebFetch` against the library's official docs and note that.
+
+# Method
+
+1. **Identify libraries and frameworks** the solution would likely touch.
+2. **Verify each library API** via context7 (above).
+3. **For each candidate**, evaluate against:
+   - Fit with existing patterns (per scout report).
+   - YAGNI: does it need abstractions beyond what this task requires?
+   - Test-ability: can it be driven by tests seed.md permits — no internal mocks, no mocked DB?
+   - Reversibility: if it proves wrong post-implementation, what is the blast radius?
+4. **Rank candidates.** State your recommendation. Name what would flip the decision.
+
+# Output
+
+Write the memo to `docs/research/<slug>.md`. Format:
+
+```
+# Pattern Research — <task>
+
+## Candidate A: <short name>
+- **Summary**: <1–2 sentences>
+- **API references (current)**:
+  - `<lib>@<version>` — <specific API> — <context7 or doc URL>
+- **Fits**: <yes/no — anchored to a Scout observation>
+- **Tests it enables**: <kinds of tests>
+- **Tradeoffs**: <honest, not marketing>
+
+## Candidate B: ...
+
+## Recommendation
+<Which candidate, and what would flip the decision.>
+
+## Open questions
+<Things a human reviewer must decide before the spec is written.>
+```
+
+After writing the file, append `"research"` to `workflow.json → completed`.
+
+Tell the user: `Research memo at <path>. Next: /spec.`
+
+# Constraints
+
+- **No code generation.** Memo only.
+- **No API assertion without a context7/docs reference.** "Unable to verify" is the honest answer when you hit a gap; do not guess.
+- **No reimplementing what an approved dependency provides** (YAGNI, per seed.md).
+- **Prefer 2–3 candidates over 6+.** Half-baked options are noise.
+- **The recommendation is a recommendation.** The human reviewer decides at `/spec`.
+- **Project source is read-only.** The only write is to `docs/research/<slug>.md`.