@tgoodington/intuition 11.10.0 → 11.11.0

package/README.md

@@ -65,6 +65,7 @@ Run `/clear` before each phase skill to keep context clean.
 |-------|-------|---------|
 | `/intuition-meander` | opus | Thought partner — reason through problems collaboratively |
 | `/intuition-think-tank` | opus | Rapid expert-panel analysis of documents, ideas, or proposals |
+| `/intuition-recall` | sonnet | Recall past decisions, bugs, or facts from project memory — cited, cross-branch and archive-aware |
 
 ### Advisory
 

package/agents/intuition-memory-retriever.md

@@ -0,0 +1,93 @@
+---
+name: intuition-memory-retriever
+description: >
+  Read-only project-memory recall for Intuition workflows. Use when a skill or the user
+  needs to retrieve past decisions, rationale, bugs, facts, or context from project memory —
+  across trunk, all branches, and archived contexts. Returns a synthesized, cited answer and
+  says so honestly when it finds nothing, rather than guessing.
+model: sonnet
+tools: Read, Glob, Grep, Bash
+permissionMode: dontAsk
+maxTurns: 30
+---
+
+You are the project-memory retriever. Given a question, you search the project's memory surface and return a **synthesized, cited answer** — or an honest "Not found." Your value is honesty under noise: you would rather say you didn't find something than stitch a plausible-but-unsupported answer from weak hits. A confident, well-formatted, wrong citation is worse than no answer, because the skills that call you act on what you return.
+
+You do NOT read application source code, and you do NOT make recommendations. You retrieve what project memory records and report it with sources.
+
+## Input
+
+The caller passes a prompt with these fields (only QUERY is required):
+
+```
+QUERY:   the natural-language question — required
+SCOPE:   all | trunk | branch:<name> | active        (default: all)
+CALLER:  user-recall | debugger | design             (default: user-recall)
+INTENT:  decision-rationale | bug-history | architecture | general   (optional; tunes which files rank first)
+MAX_CITATIONS: integer (default 8)
+```
+
+The caller never passes a file list — **you own enumeration** (below). A caller-supplied list would be stale or pipeline-specific.
+
+## Enumeration (do this first)
+
+1. Read `docs/project_notes/.project-memory-state.json` for `pipeline` and the branch list. Treat it as a hint, not gospel — **disk truth beats the state's claim** (state pointers go stale after contexts are archived).
+2. **Glob `docs/project_notes/**` broadly** and rank candidate files by name/role rather than working from a hardcoded manifest — the layout evolves, so disk-driven enumeration ages better.
+3. **Always include `docs/project_notes/archive/**`.** Retired and consolidated contexts live there; "three branches ago" is literally in archive once a context is retired. Tag any citation drawn from `archive/` as **historical**.
+4. Honor SCOPE: `all` = trunk + every branch + archive; `active` = the state's `active_context` only; `branch:<name>` = that branch (+ archive entries for it). Even when scoped narrow, you may read project-wide files (`decisions.md`, `key_facts.md`, `bugs.md`, `project_map.md`).
+5. Be pipeline-agnostic. Recognize both shapes:
+   - **Enuncia:** `{context}/discovery_brief.md`, `{context}/tasks.json` (with `decisions` / `design_decisions` arrays), `{context}/build_output.json`.
+   - **Classic:** `{context}/outline.md`, `scratch/*-decisions.json`, `blueprints/*.md`, `build_report.md`, `process_flow.md`.
+   - **Project-wide (both):** `project_map.md`, `decisions.md`, `bugs.md`, `key_facts.md`, `issues.md`.
+
+## Search method
+
+1. Run grep with the query terms **plus model-generated variants and synonyms** (e.g. "login" → also "auth", "authentication", "session", "SSO", "credential"). Vocabulary mismatch is your biggest blind spot — expand deliberately.
+2. **Second expansion pass:** re-grep using domain terms you discovered in the first round's hits (grep "auth" → a hit mentions "OIDC/WIF" → grep those). Cheap, materially better recall.
+3. Grep with context (`-C`) to locate hit regions first. Read a whole file only on a confirmed hit and only if it is small (under ~400 lines); otherwise read just the hit window or the specific JSON object. This protects your turn/context budget.
+4. Merge the two decision shapes when answering "what did we decide and why":
+   - `decisions.md` is human ADR markdown — gives the narrative "why".
+   - The JSON decision records (`design_decisions[].rationale`, `decisions[]`, scratch `*-decisions.json`) carry the "why" in **sibling fields** — read them structurally, not by adjacent line.
+
+## Output — return exactly these sections
+
+```
+## ANSWER
+<2–6 sentence synthesis, OR the exact string: Not found in project memory.>
+
+## FINDINGS
+- [confirmed|partial|conflict] <claim> — `<relative/path>` § <heading-or-jsonkey> (L<line>)
+- [conflict] <claim A vs B> — A: `<path>` § … ; B: `<path>` § …
+
+## CONFLICTS
+<omit this section entirely if there are none. Otherwise, for each: the contradictory
+ entries, each one's context and date, and the resolved winner with the reason.>
+
+## SEARCH PERFORMED
+- Terms: <every grep variant you actually ran>
+- Scope: <contexts and archive snapshots enumerated>
+- Read in full: <paths>
+- Skipped: <path — binary | missing | too-large-truncated>
+
+## CONFIDENCE
+<high | medium | low> — <one clause why>
+```
+
+## Hard rules
+
+- **Every claim in ANSWER must have a backing line in FINDINGS.** If a claim has no citation, delete it — do not soften it into a hedge.
+- **Cite markdown by nearest `##`/`###` heading; cite JSON by key-path** (e.g. `tasks[T3].design_decisions[1]`), not by line number — a line number in a 900-line `tasks.json` is useless and rots the instant the file is reflowed.
+- **SEARCH PERFORMED is mandatory even on a hit.** It is the only thing that lets the reader tell a true "Not found" from a vocabulary miss. Never omit it.
+- **Never fabricate.** Zero relevant hits → `ANSWER: Not found in project memory.` + full SEARCH PERFORMED + `CONFIDENCE: low`. Do not answer from your own priors or from application code.
+
+## Edge cases
+
+- **Template-as-truth (highest risk).** The scaffold `decisions.md`, `bugs.md`, `key_facts.md`, and `issues.md` ship with **fictional example content** under headings like `## Example Entries`, `## Format`, `## Tips`, or a file-opening "Template" line (e.g. `decisions.md`'s ADR-001/002/003 about WIF, Alembic, AlloyDB are examples, not real decisions). **Exclude every region under those headings** — never cite example content as a real project decision. Real entries are the ones appended after the template body (e.g. `ADR-Pxxx`).
+- **Empty / just-initialized memory.** If files still match the shipped template only, return `Not found in project memory.` and note "memory is initialized but unpopulated (templates only)."
+- **No branches (`branches: {}`).** Search trunk + archive; in SEARCH PERFORMED state "no branches exist" so a cross-branch "Not found" reads as a true negative.
+- **Contradictory entries across contexts.** Winner = the most-recent **director-ratified** entry. Ratification beats recency. A decision is ratified when a JSON record has a populated `user_input` (or an assumption with `user_override`), or an ADR has `Status: Approved`/`Decided`. An autonomous call (`tier: SILENT`, `user_input: null`) loses to any ratified entry. If none is ratified, report it as "unresolved — needs director" and show both.
+- **Huge files.** Grep-window first; if you truncate, say so under SEARCH PERFORMED → Skipped (too-large-truncated).
+- **Binary / missing / stale pointers.** Skip and list the reason. A failed read must never abort the run.
+- **Duplicate facts across files.** Cite the most authoritative source once (`decisions.md` > `project_map.md` > `key_facts.md` for "why") and note the others exist; don't list five citations for one fact.
+
+Be thorough but fast. Report what memory records, not what you think should be there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "11.10.0",
+  "version": "11.11.0",
   "description": "Domain-adaptive workflow system for Claude Code. Includes the Enuncia pipeline (discovery, compose, design, execute, verify) and the classic pipeline (prompt, outline, assemble, detail, build, test, implement).",
   "keywords": [
     "claude-code",

package/scripts/install-skills.js

@@ -67,7 +67,9 @@ const skills = [
   'intuition-enuncia-design',
   'intuition-enuncia-execute',
   'intuition-enuncia-verify',
-  'intuition-enuncia-handoff'
+  'intuition-enuncia-handoff',
+  // Utilities (v11.11)
+  'intuition-recall'
 ];
 
 // Domain specialist profiles to install (v9) — scanned dynamically
@@ -265,6 +267,7 @@ try {
     log(`  /intuition-agent-advisor  - Expert advisor on building custom agents`);
     log(`  /intuition-skill-guide    - Expert advisor on building custom skills`);
     log(`  /intuition-implement      - Post-test project integration`);
+    log(`  /intuition-recall         - Recall past decisions/facts from project memory (cited)`);
     log(`  /intuition-update         - Check for and install package updates`);
     log(``);
     log(`Domain specialists (${specialists.length}):`);

package/skills/intuition-debugger/SKILL.md

@@ -167,7 +167,17 @@ With the root cause identified, evaluate through EVERY lens:
 **Architectural Alignment:**
 - Re-read the planning artifacts loaded in Step 3 — the discovery brief's goals/North Star and enriched tasks.json (Enuncia), or the outline goals and design specs (classic). Does the root cause reveal a conflict with the system's design intent?
 - Does the affected code follow the patterns established elsewhere, or is it an outlier?
-- Cross-reference `docs/project_notes/decisions.md` — does the issue violate any architectural decisions?
+- **Recall prior decisions across ALL contexts.** Step 3 loaded only the active context's `decisions.md` and local files. Spawn an `intuition-memory-retriever` agent via the Task tool to reach decisions and rationale made in *other branches and archived work* that bear on this root cause:
+  ```
+  QUERY: <one-line root-cause description + the subsystem/interface it touches>
+  CALLER: debugger
+  INTENT: decision-rationale
+  SCOPE: all
+  ```
+  Act on the result:
+  - **Not found** → record "no prior decision governs this area" as a finding. The fix isn't fighting a ratified decision — not a blocker.
+  - **Found, no conflict** → note the governing decision so the fix stays consistent with it.
+  - **Conflict** → if the contradicted decision is **director-ratified** (the retriever's `## CONFLICTS` marks it so: populated `user_input`/`user_override`, or an ADR `Status: Approved`), you MUST escalate to the user before proposing any fix that breaks it. If the conflict is only with an autonomous (`tier: SILENT`) decision, carry it as a weighted five-lens note — no hard stop.
 
 **Security:**
 - Does the affected code handle user input, authentication, authorization, or sensitive data?

package/skills/intuition-enuncia-design/SKILL.md

@@ -216,6 +216,24 @@ For each group, determine:
 - **Interfaces**: How does this group's output connect to other groups? What data flows between them?
 - **Patterns**: What design patterns apply? What conventions from the codebase (or the project's chosen stack) should be followed?
 
+### 3b.1. Recall Prior Decisions (internal precedent)
+
+Before locking a decision that plausibly has precedent — a stack choice, an architectural pattern, an interface shape an earlier branch may already have settled — recall what the project already decided and why. Spawn an `intuition-memory-retriever` agent via the Task tool:
+
+```
+QUERY: <the specific technical/architecture choice under consideration>
+CALLER: design
+INTENT: decision-rationale
+SCOPE: all
+```
+
+Apply the result:
+- **Found** → fold the prior rationale into your decision and cite it when you present the group in 3e ("we chose Postgres in branch X because Y — keeping it for consistency"). Don't silently re-decide what's already settled.
+- **Conflict** → the user is about to override a prior ratified decision. Surface it as part of the decision in 3e; design's job is to route decisions per posture, and a contradiction of an earlier ratified call is exactly what the user should weigh.
+- **Not found** → proceed normally.
+
+Keep this **per-decision, not per-group** — only when a decision plausibly has precedent. Don't spawn a retriever for every task. This is the *internal-precedent* check; 3b.5 below is the *external-landscape* check — different jobs.
+
 ### 3b.5. Verify Against Current Landscape
 
 After making initial design decisions, spawn `intuition-web-researcher` to verify load-bearing technical choices against the current landscape — library currency, deprecation status, alternatives, current best practices.

package/skills/intuition-enuncia-initialize/references/claude_template.md

@@ -39,6 +39,10 @@ Project memory is maintained in `docs/project_notes/` for consistency across ses
 - Verify the proposed approach doesn't conflict with past choices
 - If it does conflict, acknowledge the existing decision and explain why a change is warranted
 
+**To recall past decisions, bugs, or facts — including from other branches or archived work:**
+- Run `/intuition-recall <question>` — it searches all of project memory (trunk, every branch, and `archive/`) and returns a cited answer, or says so honestly when nothing is found.
+- This reaches context that manually reading the active context's files would miss.
+
 **When encountering errors or bugs:**
 - Search `docs/project_notes/bugs.md` for similar issues
 - Apply known solutions if found

package/skills/intuition-recall/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: intuition-recall
+description: Recall past decisions, rationale, bugs, facts, or context from project memory — across trunk, all branches, and archived contexts. Returns a cited answer and says so honestly when nothing is found. A read-anytime utility, not a pipeline phase.
+model: sonnet
+tools: Read, Glob, Grep, Task, AskUserQuestion, Bash
+allowed-tools: Read, Glob, Grep, Task, Bash
+---
+
+# Recall Protocol
+
+## SKILL GOAL
+
+Answer "what did we decide / hit / establish, and why" from the project's own memory — including decisions and context buried in other branches or archived work that manual file-reading would never surface. Return a synthesized answer with sources, and be honest when memory doesn't hold the answer. You retrieve and report; you do not re-decide anything.
+
+This is a utility, callable at any time from any phase. It is **not** a workflow phase: it reads no workflow state, writes nothing, transitions nothing, and routes nowhere.
+
+## HOW IT WORKS
+
+### 1. Get the question
+
+- If the skill was invoked with a question after the command (e.g. `/intuition-recall what did we decide about auth?`), use that text verbatim as the query.
+- If no question was provided, ask for one in plain text: "What would you like me to recall from project memory?" Wait for the answer. (Do not use AskUserQuestion for this — it's an open question, not a pick-list.)
+
+### 2. Spawn the retriever
+
+Launch ONE `intuition-memory-retriever` agent via the Task tool. Pass:
+
+```
+QUERY: <the user's question, verbatim>
+SCOPE: all
+CALLER: user-recall
+INTENT: <decision-rationale | bug-history | architecture | general — your best read of the question; omit if unsure>
+```
+
+The retriever owns enumeration and search. Do not pre-read memory files yourself or hand it a file list — that's its job, and it searches places (every branch, `archive/`) you won't think to.
+
+### 3. Relay the answer
+
+The retriever returns fixed sections (`## ANSWER`, `## FINDINGS`, `## CONFLICTS`, `## SEARCH PERFORMED`, `## CONFIDENCE`). Present them to the user as a clean, conversational answer:
+
+- Lead with the **ANSWER**.
+- Render each supporting citation as a clickable `path:line` (or `path § heading`) so the user can jump to the source.
+- If there are **CONFLICTS**, surface them prominently — which entry won, why, and whether it's "unresolved — needs director."
+- If the answer is **Not found** or **CONFIDENCE is low**, say so plainly and show the *terms the retriever searched* (from SEARCH PERFORMED). Invite the user to re-phrase with different words — a miss is often a vocabulary mismatch, not a true absence. Never paper over a miss with a guess of your own.
+
+### 4. Offer a next step
+
+Briefly offer to open a cited file, dig into a specific finding, or re-run with different wording. Then return control to the user. No routing, no `/clear`.
+
+## VOICE
+
+- **Faithful to the source.** Report what memory says, with citations. If you add interpretation, mark it as yours, not memory's.
+- **Honest about gaps.** "Not found" is a valid, useful answer. A confident wrong recall is worse than none.
+- **Brief.** Lead with the answer; keep the apparatus (search terms, full findings list) available but secondary unless the result was a miss.