create-claude-cabinet 0.46.0 → 0.48.0

package/templates/skills/debrief-classic/phases/methodology-capture.md

@@ -0,0 +1,223 @@
+# Methodology Capture — Instruction Phase
+
+**Position:** After record-lessons, before upstream-feedback.
+
+**This is an instruction phase** — it tells Claude when and how to
+capture methodology-level artifacts from a session. It ships with CC
+and should not be deleted or replaced with `skip: true`. If the phase
+file is removed, the behavior described here still applies via the
+default-from-SKILL.md mechanism.
+
+## What this phase does
+
+Standard debrief captures individual lessons ("user scope hints are
+defensive signals"), discrete decisions ("used append-only history
+table"), and documentation fixes. It does NOT capture the **reasoning
+chain** or **self-critique layer** behind load-bearing methodology —
+the kind of work where *how you did it* is as important as *what you
+did*.
+
+This phase fills that gap when the session's work warrants it. Most
+sessions don't. The phase is gated on detection heuristics so bug
+fixes and small refactors skip silently.
+
+## Test for "core work"
+
+Adapted from the source feedback that motivated this phase:
+
+> Not every session, but when the work is core to the product's
+> differentiation or legitimacy — the thing the founder would want
+> on a pitch deck, the thing a customer would ask "how do I know
+> this works?" about.
+
+If the session produced methodology that could be asked about, defended,
+demonstrated, or replicated — it's core work. If it was routine
+application of existing methodology, it isn't.
+
+## Workflow
+
+### 1. Detect methodology-level signals (silent)
+
+Scan the session for any of these signals. Fire only when one or more
+match. Otherwise skip silently and proceed to upstream-feedback.
+
+- **New skill created** in `.claude/skills/` or `templates/skills/`
+  (including new `phases/*.md` files that define orchestration logic,
+  not just content)
+- **Multi-phase pib-db project** with actions named "Phase N…" where
+  N ≥ 2 (or equivalent work-tracker multi-phase structure)
+- **Audit artifacts** written to structured run directories
+  (e.g., `audit-runs/<timestamp>/`)
+- **Multi-subagent parallel choreography** used during this session
+  (two or more agents spawned in a single parallel batch with
+  coordinated roles)
+- **Gate scripts with pass/fail thresholds** created this session
+  (exit codes, verification-breadcrumbs, blocking-phase markers)
+- **Disposition registers or calibration harnesses** created this
+  session (files that record triage outcomes, calibration examples,
+  decision rationales for future reference)
+- **New convention docs** under `templates/cabinet/` or equivalent
+  reference-docs location that encode cross-skill or cross-project
+  invariants
+
+Detection should be based on evidence from this session — git diff,
+files written, subagent spawn counts. Do not guess. If ambiguous,
+err toward not-firing (false positives waste the user's attention;
+false negatives only cost one methodology record).
+
+### 2. Ask once (if signals fire)
+
+Present the detected signals in a single sentence, then ask a
+four-choice question. Do not ask open-ended questions. Do not batch
+with other debrief prompts.
+
+> "This session produced methodology work: [brief list of detected
+> signals — e.g., 'a new skill, a 4-phase project, a gate script'].
+> Capture:
+> (a) **internal critique-edges record** (reasoning chain, skeptic's
+>     counters, off-ramps)
+> (b) **narrateable summary** (200-400 words for external audiences)
+> (c) **both**
+> (d) **neither**"
+
+If the user says (d), stop silently — the detection fired but the
+user declined. Do not re-prompt next session for the same work.
+
+### 3. Write the requested artifacts
+
+Write to `.claude/methodology/YYYY-MM-DD[-slug]-<type>.md` where
+`<type>` is `internal` or `narrative`. Slug is a short phrase derived
+from the session's focus. If the directory doesn't exist, create it.
+
+**Path override:** If `phases/methodology-capture.md` in the project
+overrides the default location (e.g., some projects may want
+`docs/methodology/` instead), respect the override.
+
+### 3a. Internal critique-edges record
+
+For each significant decision made this session, record:
+
+```markdown
+### [Decision in one sentence]
+
+**Claim:** What we decided and why it's defensible.
+
+**Evidence:** What we had in hand — measurements, prior cases,
+documentation, stakeholder input.
+
+**Skeptic's critique:** Where a thoughtful reader could press. What
+would a contrarian cabinet member flag? What dismissals might be
+too quick?
+
+**Counter:** Our response to the critique — the reason the decision
+still stands despite the pressure.
+
+**Off-ramp:** What would change our mind? What observation, metric,
+or shift in constraints would cause us to revisit this?
+```
+
+A session typically has 2-6 significant decisions worth this treatment.
+Not every micro-choice. The test: "would a future session executing
+this work benefit from knowing the skeptic's critique?"
+
+### 3b. Narrateable summary
+
+Write 200-400 words, external-audience-friendly. Readable by a
+non-insider. No skill-specific jargon unless inlined with a
+one-phrase gloss.
+
+Structure (flexible — adapt to what the work is):
+
+- **The problem** (1-2 sentences about the friction or opportunity)
+- **The approach** (what methodology was applied or built)
+- **Specifics and scale** (concrete numbers, files, components — enough
+  that a reader can sense the work's weight)
+- **What makes this work** (the load-bearing mechanism, the non-obvious
+  insight)
+- **How you'd know it's working** (what metric, signal, or demonstration
+  would confirm it)
+
+Format so it could be pasted into a pitch deck section, an about page,
+an investor update, a collaborator email, or a customer FAQ.
+
+### 3c. Index the new artifacts (required)
+
+These records are version-controlled **project thought-record**, not
+ephemera (see `.claude/rules/artifacts-of-thought.md`). In the same
+change that writes a doc, add an index line for it to
+`.claude/methodology/README.md` — date, title, one-line hook, and a
+link. Create that index file if it doesn't exist yet. An unindexed
+record is an invisible record, and the `/validate`
+`artifacts-of-thought` check fails on any methodology doc git isn't
+tracking — so a doc left unindexed-and-uncommitted will break
+validation. If the project routes output to a custom location (see
+Path override), index it there instead.
+
+### 4. Integration with the debrief report
+
+At the end of the report phase, surface any methodology artifacts
+created this session:
+
+> **Methodology captured this session:**
+> - `.claude/methodology/2026-04-18-deferred-trigger-mechanism-internal.md` — 4 decisions with skeptic counters
+> - `.claude/methodology/2026-04-18-deferred-trigger-mechanism-narrative.md` — 340 words
+
+One-line preview plus file path for each. Don't paste the content —
+the files are the artifact.
+
+## Project overrides
+
+Projects MAY override behavior by editing this phase file:
+
+- **`skip: true`** — entire phase skipped, including detection.
+- **Custom detection heuristics** — replace the signal list above with
+  project-specific triggers.
+- **Custom templates** for internal/narrative records — some projects
+  may want different sections or formats.
+- **Different output location** — e.g., `docs/methodology/` for
+  projects that want methodology visible to collaborators via
+  standard docs tooling.
+
+The default (this file's content as shipped) should be reasonable for
+any project doing occasional core methodology work.
+
+## Calibration
+
+**Without this phase (what happens today):**
+Session produces a new multi-phase skill with gate scripts, a convention
+doc, and a calibration harness. Debrief captures three discrete lessons
+("user scope hints are defensive," "append-only history preserves
+audit trail," etc.) and closes. Six weeks later, someone asks "why did
+you build it this way instead of [X]?" — the answer is fully in
+someone's head (maybe nobody's, if attention has moved on), and the
+skeptic's critique that was considered and addressed during the work
+isn't recoverable. The narrative layer that would let a stakeholder
+understand what was done at a glance doesn't exist.
+
+**With this phase:**
+Same session fires the multi-phase + new-skill + convention-doc
+signals. User picks (c) both. Claude writes:
+- `internal.md` with 4 decisions, each including the skeptic's
+  critique and the off-ramp (so a future disagreement has ground
+  to stand on)
+- `narrative.md` in 340 words, pastable into a roadmap email
+When a stakeholder asks six weeks later, the artifact exists. When
+the project revisits the decision, the off-ramps are legible.
+
+The phase costs maybe 3-5 minutes per session it fires. It fires on
+a minority of sessions. Most sessions are untouched.
+
+## Relationship to adjacent phases
+
+- **record-lessons** (step 9): captures individual lessons. Parallel
+  layer: granular, fact-shaped. This phase captures the layer above:
+  compositional, reasoning-shaped.
+- **upstream-feedback** (step 11): captures CC friction. Different
+  input (what hurt) and destination (CC source repo feedback/).
+- **skill-discovery** (step 12): asks whether the workflow should
+  become a skill. Different output (a skill file), different trigger
+  (repeatability, not depth).
+
+These four phases together cover: discrete lessons (9), methodology
+layer (this), friction (11), and workflow-worth-encoding (12). Each
+fills a different bucket. None subsumes another.

package/templates/skills/debrief-classic/phases/qa-handoff-sweep.md

@@ -0,0 +1,78 @@
+# QA-Handoff Sweep (instruction phase)
+
+Hand off every worktree→main merge from this session that still needs
+post-merge QA — so the operator never has to remember to run
+`/qa-handoff` after each merge. A session that merged several branches
+needs several handoffs; this performs all of them.
+
+This is an **instruction phase** — it ships with debrief and always
+runs (it is not skipped by the customization-phases default). It
+self-skips at runtime when there is nothing to hand off or when the
+`/qa-handoff` skill is not installed.
+
+## When it self-skips (silent, not a failure)
+
+- `/qa-handoff` is not installed (no `templates`/installed
+  `skills/qa-handoff/` — the watchtower module is absent). Skip
+  silently; the rest of debrief continues.
+- No worktree→main merges happened this session.
+- Every merge this session is already represented in the watchtower
+  inbox as a `qa-handoff` item (already handed off).
+
+## Steps
+
+1. **Find this session's merges into main.** Use the inventory from
+   debrief step 1. Identify merge commits landed on `main` during this
+   session:
+
+   ```bash
+   git log --merges --since='<session start, e.g. 6 hours ago>' \
+     --format='%H %P %s' main
+   ```
+
+   Resolve each merge to the branch that was merged from its **second
+   parent** (`<merge-sha>^2`), NOT from the subject line. The subject
+   regex (`Merge branch 'X'`) is unreliable — a merge made with a
+   non-default message, a squash, or a PR-style merge resolves to the
+   wrong name (e.g. `main`), which would then be handed off as a bogus
+   "branch". The second parent is the actual merged tip regardless of
+   message:
+
+   ```bash
+   # the merged branch name for a merge commit <sha>:
+   git name-rev --name-only --refs='refs/heads/*' "<sha>^2" 2>/dev/null
+   # fall back to the second-parent SHA itself if it has no branch ref
+   ```
+
+   This correctly resolves both `mux/<slug>` and workflow
+   `worktree-wf_*` merges. Keep the merge commit SHA on main as the
+   dedup key. Include non-merge integrations only if this repo
+   fast-forwards `mux/*` work onto main without a merge commit.
+
+2. **Dedup against handoffs already filed.** For each merge SHA, check
+   whether a `qa-handoff` inbox item already records it (its
+   `evidence.merged_commit` equals the SHA). Read the inbox via the
+   installed queue API (see `/qa-handoff` Step 5 for the
+   `watchtower-queue.mjs` path) or list `queue/items/*.json` under the
+   watchtower dir and match on the merged SHA. Drop merges already
+   handed off — never file a duplicate.
+
+3. **Hand off the remainder.** For each remaining merge, invoke
+   `/qa-handoff <branch>`. That skill does the full job — packages what
+   merged + what it could not runtime-verify, files the inbox item, and
+   `mux qa dispatch`es it to the desk's QA station. Run them one at a
+   time; each is cheap.
+
+4. **Report.** One line per handoff performed (what merged, the short
+   SHA, where it dispatched), and one line if any merges were skipped as
+   already-handed-off. If nothing was handed off, say nothing — silence
+   is the correct output of an empty sweep.
+
+## Why this is a phase, not a separate skill
+
+The sweep belongs to session close: it knows the session's merges from
+debrief's inventory, and it should run whether the operator closes with
+plain `/debrief` or with `/session-handoff` (which wraps debrief). A
+phase gives both verbs the behavior from one definition. `/qa-handoff`
+itself stays the single source of truth for *how* a handoff is
+packaged — this phase only decides *which* merges still need one.

package/templates/skills/debrief-classic/phases/record-lessons.md

@@ -0,0 +1,177 @@
+# Record Lessons — Route Session Outputs to Their Real Homes
+
+This is debrief's second irreducible purpose: make sure the next session
+is smarter than this one. Without it, the system does work but doesn't
+learn from it.
+
+Lessons are perishable. A lesson captured while context is fresh is
+worth ten captured from memory next week.
+
+## The Routing Principle
+
+Every session output has **exactly one primary home**. The home must
+have a forcing function — something that keeps the content accurate
+when the code it describes changes. Loose `.md` files next to code
+are the wrong home: they rot silently because nothing invalidates
+them when the system evolves.
+
+**Each output has one home. Don't double-store.** A decision captured
+via `/cc-remember` doesn't also need a CLAUDE.md entry "for backup."
+Duplication just creates two things to keep in sync.
+
+## Routing Decision Tree
+
+For each thing you'd want future sessions to know, pick the single
+best home:
+
+### Decisions — "we chose X over Y because Z"
+
+Architectural choices, tradeoff resolutions, accepted gaps, rejected
+alternatives.
+
+**Primary home:** built-in memory via `/cc-remember` (or
+`scripts/write-memory-file.mjs` programmatically). One `.md` file per
+decision, descriptive slug, indexed in MEMORY.md.
+
+```bash
+node scripts/write-memory-file.mjs \
+  --slug "decided_<short_name>" \
+  --description "<one-line summary>" \
+  "We chose X over Y because Z. Tradeoffs considered: ..."
+```
+
+**Also add to CLAUDE.md** only if the decision is load-bearing enough
+that *every* session needs to know it at startup (not just sessions
+that touch the relevant code). Examples: "auth is per-user via FastAPI
+Users (no shared passwords)" is load-bearing. "We rejected a specific
+library option after evaluation" is not — memory is enough.
+
+### Project constraints / conventions / gotchas
+
+Environmental quirks, dev-workflow requirements, "this project has a
+weird setup" facts.
+
+**Primary home:** inline in `CLAUDE.md` or the project briefing. These
+files get edited when the code changes — the forcing function is that
+they're load-bearing for every session, so staleness surfaces fast.
+
+Use a built-in memory file (`constraint_<short_name>.md` via
+`/cc-remember`) only for nuanced constraints where the explanation is
+too long for CLAUDE.md. Project-specific quick constraints belong
+inline.
+
+### Conditional revisits — "do X later when Y happens"
+
+"If we ever get multiple concurrent users, add a token blocklist."
+"When curl becomes annoying, build a /settings UI."
+
+**Primary home:** pib-db deferred action with `trigger_condition`.
+
+```
+pib_create_action text="..." status="deferred" trigger_condition="..."
+```
+
+Orient's deferred-check phase re-evaluates these every session. If the
+condition has fired, the user gets asked; if it's obsolete, it gets
+marked so. No silent rot.
+
+### CC upstream friction embedded in a project observation
+
+Sometimes a project-scoped observation contains a CC-applicable piece:
+"in this project auth tests are hard, AND cabinet-qa should flag this
+pattern in any auth work." That's two things, not one.
+
+**Split it.** Route the project piece to its home
+(`/cc-remember` / CLAUDE.md / trigger). Route the CC piece to the
+upstream-feedback phase (step 11) where it will be drafted and
+delivered. Don't bury the upstream piece inside a project decision
+doc — it will never find its way home.
+
+### Lessons, gotchas, discoveries (not decisions, not constraints)
+
+"We learned that X behaves differently from docs." "This pattern
+works." "The CI was green but prod failed because…"
+
+**Primary home:** built-in memory via `/cc-remember --slug
+"lesson_<short_name>" ...`. One `.md` file per lesson.
+
+### User preferences
+
+Style choices, workflow preferences, corrections the user made.
+
+**Primary home:** built-in memory via `/cc-remember --slug
+"user_prefers_<thing>" ...`. Or CLAUDE.md if it's a preference that
+should fire on every session start (e.g., "always use pnpm").
+
+## Lessons-Applied-to-Own-Output Scan
+
+**Before sending this debrief report**, scan the lessons you just
+captured *this session* against the report you're about to write.
+Does the report itself violate what was learned?
+
+Concrete example: this session captured a `lesson_dont_trust_estimates`
+memory ("user's time estimates are overcalibrated, recalibrate
+downward"). The debrief report then includes "this took 30 minutes"
+phrasing — directly contradicting the just-captured lesson.
+
+For each captured lesson, ask: *Is the debrief report observing this
+lesson?* If not, rewrite the report before sending. Captured but
+not applied is the same failure mode that bit us with omega; the
+write path doesn't matter, the read-and-apply step does.
+
+## The Anti-Pattern: Loose Project-Scoped .md Files Outside the Memory Dir
+
+**Do not write `feedback-project-*.md`, `decision-*.md`, or similar
+loose .md files next to code or in arbitrary project subdirectories.**
+This pattern rots — in one audited case, 4 of 5 such files went stale
+within 7 days because the underlying code changed and the files had
+no forcing function to catch it.
+
+If you are tempted to write a loose .md file:
+- Is it a decision? → `/cc-remember --slug "decided_..."`
+- Is it a constraint everyone needs? → CLAUDE.md / briefing
+- Is it a conditional revisit? → pib-db deferred trigger
+- Is it CC upstream friction? → upstream-feedback phase
+- None of the above? → it probably doesn't need recording at all
+
+## Before Writing — Contradiction Check
+
+For each memory you're about to capture, search the memory dir for
+existing entries on the same topic:
+
+```bash
+grep -i "<topic>" ~/.claude/projects/<slug>/memory/*.md
+```
+
+If an existing entry contradicts or is superseded by the new one,
+edit the old file with a `**Superseded by <new-slug>.md on <date>**`
+header. Keep the old file for history — don't delete unless the old
+entry was wrong (rather than just outdated).
+
+This is the forcing function that turns memory into a living record
+instead of another pile of rotting notes.
+
+## What NOT to Record — Anywhere
+
+- Code patterns derivable by reading current files
+- Git history (use `git log`)
+- Debugging solutions (the fix is already in the code; the commit
+  message has the context)
+- Anything already in CLAUDE.md files
+- Ephemeral task details only relevant to this session
+- "We made progress on X" session summaries — that's what git is for
+
+## Report What Was Routed
+
+Tell the user what went where so they can audit the routing:
+
+```
+Routed this session:
+- 1 decision → memory: decided_jwt_revocation.md
+- 1 constraint → article-rewriter/CLAUDE.md (tsc must run from frontend)
+- 1 deferred trigger → pib-db act:xxxxxxxx (add blocklist if multi-user)
+- 1 upstream piece → CC feedback outbox (cabinet-qa testability)
+```
+
+This is also how you catch routing errors: if everything ended up in
+memory files, the routing discipline didn't actually run.

package/templates/skills/debrief-classic/phases/report.md

@@ -0,0 +1,59 @@
+# Report — How to Present the Debrief Summary
+
+Define how to present the debrief results to the user. This is the
+presentation phase — it can be skipped in quick mode without losing
+any operational value (all core phases still run).
+
+When this file is absent or empty, the default behavior is: present a
+brief summary of work closed, state updated, and lessons recorded. To
+explicitly skip the report, write only `skip: true`.
+
+## What to Include
+
+- **Format** — what sections to include in the report
+- **Tone** — how to communicate results
+- **Modes** — if your project uses different presentation modes (e.g.,
+  evening preview, verbose vs. compact)
+- **What NOT to include** — execution guides, instructions for next
+  session (the work items ARE the handoff)
+
+## Example Report Formats
+
+Uncomment and adapt these for your project:
+
+<!--
+### Standard Report
+
+Present in this order:
+1. **Work closed** — items marked complete (with references)
+2. **Feedback resolved** — comments or feedback addressed
+3. **State updated** — files and docs that were updated
+4. **Lessons recorded** — memories created or updated
+5. **Loose ends captured** — non-project items routed
+6. **Anything needing input** — keep this minimal
+
+Tone: brief, factual. The user can read the diffs.
+
+Do NOT produce "how to start next session" guides. The work items
+have the full specs. If the items' notes are insufficient, update them
+— don't compensate in chat output that vanishes with the session.
+
+### Compact Report (quick mode fallback)
+
+Bullet list, one line per category:
+- Actions completed: [list with fids]
+- Feedback resolved: [count]
+- Lessons: [files updated]
+
+No narrative, no suggestions.
+
+### Evening Preview
+
+If the session ends in the evening and your project tracks calendar
+events or scheduled work, append a brief preview of tomorrow:
+- Tomorrow's events
+- Items due tomorrow
+- Anything needing morning preparation
+
+This is enough to mentally close the session.
+-->

package/templates/skills/debrief-classic/phases/update-state.md

@@ -0,0 +1,48 @@
+# Update State — What to Update After the Session
+
+Define what state files and documentation to update so the system's
+persistent state reflects what actually happened.
+
+When this file is absent or empty, the default behavior is: check
+whether system-status.md needs updating. To explicitly skip state
+updates, write only `skip: true`. Stale state erodes
+trust — an item marked "planned" that's actually built, or a status
+file that says "incomplete" for something that shipped, makes the
+system less reliable for the next orient.
+
+## What to Include
+
+For each state artifact, provide:
+- **File** — what to check and potentially update
+- **What changes** — what kind of updates to look for
+- **How to update** — edit the file, run a command, call an API
+
+## Example State Updates
+
+Uncomment and adapt these for your project:
+
+<!--
+### System Status File
+```
+Read and update system-status.md:
+- Move completed items from "Planned" or "In Progress" to "Built"
+- Add new capabilities that didn't exist before
+- Update any counts or metrics
+- Note new known issues discovered during the session
+```
+
+### Project Documentation
+Check if any of these need updating based on what changed:
+- Root CLAUDE.md — new workflows, entity types, directories?
+- Directory-level CLAUDE.md files — changed conventions?
+- Schema or configuration files — new fields or types?
+- README — new features or changed setup instructions?
+
+Only update what actually changed. Don't rewrite docs for no reason.
+
+### Skills and Process Docs
+Review what happened during the session:
+- Did any skill's instructions prove wrong or incomplete? Fix it.
+- Did a workflow gap surface? Update the relevant skill.
+- Did you discover a better approach? Record it where it helps.
+-->