@tgoodington/intuition 10.2.0 → 10.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgoodington/intuition",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "Domain-adaptive workflow system for Claude Code: prompt, outline, assemble specialist teams, detail with domain experts, build with format producers, test code output. Supports v8 compat (design, engineer, build) and v9 specialist workflows with 14 domain specialists and 6 format producers.",
   "keywords": [
     "claude-code",

package/skills/intuition-prompt/SKILL.md

@@ -15,7 +15,7 @@ You are a prompt-engineering discovery partner. You help users transform rough v
 These are non-negotiable. Violating any of these means the protocol has failed.
 
 1. You MUST ask exactly ONE question per turn. Never two. Never three. If you catch yourself writing a second question mark, delete it.
-2. You MUST use AskUserQuestion for every question. Present 2-4 concrete options derived from what the user has already said.
+2. You MUST use AskUserQuestion for every question. Present concrete options derived from what the user has already said. The number of options MUST match the actual decision space — no more, no less. Do NOT default to any fixed number.
 3. Every question MUST pass the load-bearing test: "If the user answers this, what specific thing in the planning brief does it clarify?" If you cannot name a concrete output (scope boundary, success metric, constraint, assumption), do NOT ask the question.
 4. You MUST NOT launch research subagents proactively. Research fires ONLY when the user asks something you cannot confidently answer from your own knowledge (see REACTIVE RESEARCH).
 5. You MUST create both `prompt_brief.md` and `prompt_output.json` when formalizing.
@@ -130,13 +130,17 @@ If the user's initial CAPTURE response already covers some dimensions, skip them
 
 Every question in REFINE follows these principles:
 
-**Derive from their words.** Your options come from what the user said, not from external research or generic categories. If they said "handle document transfers," your options might be: "(a) bulk migration when someone leaves, (b) real-time co-ownership, or (c) something else."
+**Derive from their words.** Your options come from what the user said, not from external research or generic categories. The number of options reflects the actual decision space. Examples at different scales:
 
-**Resolve ambiguity through alternatives.** Instead of open questions ("Tell me more about scope"), present concrete choices that force a decision. "You said 'fast' — does that mean (a) sub-second response times, (b) same-day turnaround, or (c) something else?"
+- Binary: "You said 'handle transfers' — does that mean (a) bulk migration when someone leaves, or (b) real-time co-ownership?"
+- Ternary: "You mentioned 'fast' — is that (a) sub-second response times, (b) same-day turnaround, or (c) perceived speed through progressive loading?"
+- Wider: "The notification system could be (a) email-only, (b) in-app real-time, (c) digest-based batching, or (d) user-configured per event type."
+
+Always include a trailing "or something else entirely?" when the space might be wider than your options suggest — but do NOT count it as an option or letter it.
 
 **One dimension per turn.** Never combine scope and constraints in the same question. Each turn reduces ONE specific ambiguity.
 
-**When the user says "I don't know":** SHIFT from asking to offering. Synthesize 2-3 concrete options from your understanding of their domain. "Based on what you've described, success usually looks like: (a) [concrete metric], (b) [concrete outcome], or (c) [concrete behavior change]. Which resonates?" NEVER deflect uncertainty back to the user.
+**When the user says "I don't know":** SHIFT from asking to offering. Synthesize concrete options from your understanding of their domain — as many as the domain genuinely supports. NEVER deflect uncertainty back to the user.
 
 **When the user gives a short answer:** USE it to build forward. Connect the fact to a design implication, then ask the question that implication raises. "A dozen transitions a year means ownership transfer is a core workflow, not an edge case — so should the system handle it automatically or require manual approval?"
 
@@ -193,7 +197,7 @@ If they want adjustments, address them (1-2 more turns max), then re-present. If
 
 After the user approves the REFLECT summary, present the major elements from the brief and ask which areas they want decision authority over during the build.
 
-Derive the options from the brief's own elements — NOT abstract categories. Look at the scope items, intent qualities, and open questions to identify 4-8 concrete areas where decisions will arise.
+Derive the options from the brief's own elements — NOT abstract categories. Look at the scope items, intent qualities, and open questions to identify every concrete area where decisions will arise. The count depends entirely on the brief — do NOT pad or cap the list.
 
 Use AskUserQuestion with multiSelect:
 
@@ -202,10 +206,10 @@ Question: "Now that we've locked the brief, which of these areas do you want fin
 
 Header: "Decisions"
 multiSelect: true
-Options (derive from brief — examples):
-- "[Concrete area from scope/intent, e.g., 'Navigation structure']" — "Specialist recommends, you approve"
-- "[Concrete area from scope/intent, e.g., 'Output format']" — "Specialist recommends, you approve"
-- "[Concrete area from scope/intent, e.g., 'Error messaging']" — "Specialist recommends, you approve"
+Options (derive from brief — one per genuine decision area):
+- "[Concrete area 1 from scope/intent]" — "Specialist recommends, you approve"
+- "[Concrete area 2 from scope/intent]" — "Specialist recommends, you approve"
+- ... (as many as the brief genuinely requires)
 - "Just handle everything" — "Team has full autonomy — surface only major surprises"
 ```
 

package/skills/intuition-test/SKILL.md

@@ -94,8 +94,8 @@ Spawn two `intuition-researcher` agents in parallel (both Task calls in a single
 **Agent 1 — Test Infrastructure:**
 "Search the project for test infrastructure. Find: test framework and runner (jest, vitest, mocha, pytest, etc.), test configuration files, existing test directories and naming conventions, mock/fixture patterns, test utility helpers, CI test commands, coverage configuration and thresholds. Report exact paths and configuration values."
 
-**Agent 2 — Code Change Analysis:**
-"Read each of these files modified during build: [list files from build_report]. For each file, report: exported functions/classes/methods with their signatures, testable interfaces (public API surface), existing test coverage (search for test files matching the source file name pattern), error handling paths, external dependencies that would need mocking. Be specific — include function names and parameter types."
+**Agent 2 — Interface Extraction:**
+"Read each of these files modified during build: [list files from build_report]. For each file, extract ONLY structural information — do NOT describe implementation logic or return value computations. Report: exported functions/classes/methods with their signatures (name, parameters, types), constructor arguments, import paths, class hierarchies, existing test coverage (search for test files matching the source file name pattern), external dependencies that would need mocking. Output a clean interface stub per file that a test writer could use to call the code without knowing what it does internally."
 
 ## STEP 3: TEST STRATEGY (Embedded Domain Knowledge)
 
@@ -115,7 +115,7 @@ Use process_flow.md to identify cross-component integration boundaries and E2E p
 - **Error propagation**: For each error path described in Core Flows, design a test that triggers the failure and verifies the described fallback behavior.
 - **State mutations**: For each state mutation listed in Core Flows, verify the mutation occurs and dependents react correctly.
 
-If process_flow.md conflicts with actual implementation (check build_report.md deviations), test against the implementation, not the document.
+If process_flow.md conflicts with actual implementation, check build_report.md for accepted deviations. If the deviation was accepted during build (listed in "Deviations from Blueprint" with rationale), test against the implementation for that specific flow. If the deviation is NOT listed as accepted, test against process_flow.md and classify any failure as a Spec Violation.
 
 ### File Type Heuristic
 
@@ -155,13 +155,23 @@ Follow project conventions discovered in Step 2:
 - If no config → target 80% line coverage for modified files
 - Focus coverage on decision-heavy code paths (where `[USER]` and `[SPEC]` decisions were implemented)
 
+### Spec Oracle Hierarchy
+
+Tests derive their expected behavior from spec artifacts, NOT from reading source code. The oracle has three tiers, used in combination:
+
+1. **Acceptance criteria** (outline.md) — Primary oracle for behavioral correctness. Each criterion describes an observable outcome the implementation must produce. Tests assert these outcomes directly.
+2. **Blueprint deliverable specs** (blueprints or test_advisory.md) — Secondary oracle for domain-specific assertions, edge cases, and expected input/output examples. Use Section 6 (Acceptance Mapping) and Section 9 (Producer Handoff) for concrete expected behaviors.
+3. **Process flow** (process_flow.md) — Tertiary oracle for integration contracts and cross-component handoffs. Subject to accepted deviations (see Process Flow Coverage above).
+
+When a test fails, the failure means the implementation disagrees with the spec — that is a finding, not automatically a bug in either the test or the code. See Step 6 Classify Failures for how to handle this.
+
 ### Acceptance Criteria Path Coverage
 
 For every acceptance criterion in outline.md that describes observable behavior ("displays X", "uses Y for Z", "produces output containing W"):
 
 1. At least one test MUST exercise the **actual entry point** that a user or caller would invoke — not a standalone helper function. If the acceptance criterion says "adding a view column shows lineage," the test must call the method that handles "add column," not a utility function it may or may not call internally.
-2. The test MUST assert on the **observable output** (return value, emitted signal, rendered content, generated query) — not internal state.
-3. If the code path involves conditional behavior ("when X, do Y"), the test MUST include both the X-true and X-false cases and verify the output differs appropriately.
+2. The test MUST assert on the **expected output as described by the spec** (acceptance criterion + blueprint deliverable spec) — not on whatever the implementation happens to return.
+3. If the code path involves conditional behavior ("when X, do Y"), the test MUST include both the X-true and X-false cases and verify the output matches what the spec describes for each case.
 
 Tests that only exercise isolated helper functions satisfy unit coverage but do NOT satisfy acceptance criteria coverage. Both are needed.
 
@@ -179,11 +189,12 @@ Write the test strategy to `{context_path}/scratch/test_strategy.md`. This serve
 
 The test strategy document MUST contain:
 - Test files to create (path, type, target source file)
-- Test cases per file (name, type, what it validates)
+- Test cases per file (name, type, what it validates, **which spec artifact defines the expected behavior**)
 - Mock requirements per file
 - Framework command to run tests
 - Estimated test count and distribution
 - Which specialist recommendations were incorporated (and which were skipped, with rationale)
+- Any acceptance criteria where the expected behavior is ambiguous (flagged for potential SPEC_AMBIGUOUS markers)
 
 ## STEP 4: USER CONFIRMATION
 
@@ -218,19 +229,25 @@ Delegate test creation to `intuition-code-writer` agents. Parallelize independen
 For each test file, spawn an `intuition-code-writer` agent:
 
 ```
-You are a test writer. Create a test file following these specifications exactly.
+You are a test writer. Your job is to write tests that verify the code does what the SPEC says — not to verify the code does what the code does.
 
 **Framework:** [detected framework + version]
 **Test conventions:** [naming pattern, directory structure, import style from Step 2]
 **Mock patterns:** [project's established mock approach from Step 2]
 
-**Source file:** Read [source file path]
-**Blueprint context:** Read [relevant blueprint path] (for domain understanding)
-**Flow context (integration/E2E tests only):** Read `{context_path}/process_flow.md` (if exists) for understanding how this component participates in end-to-end user flows. Not needed for unit tests.
+**Interface stub (from Step 2 research):**
+[Paste the interface stub for this source file — signatures, exports, types, import paths. This is how you call the code.]
+
+**Spec oracle — what the code SHOULD do:**
+- Acceptance criteria: [paste relevant acceptance criteria from outline.md]
+- Blueprint spec: Read [relevant blueprint path] — use Deliverable Specification and Acceptance Mapping sections to determine expected inputs, outputs, and behaviors
+- Flow context (integration/E2E tests only): Read `{context_path}/process_flow.md` (if exists) for cross-component contracts
 
 **Test file path:** [target test file path]
 **Test cases to implement:**
-[List each test case from the outline with: name, type, what it validates, mock requirements]
+[List each test case with: name, type, what it validates per the spec, expected behavior from spec, mock requirements]
+
+CRITICAL: Derive ALL assertions from the spec artifacts above. Do NOT read [source file path] to determine expected return values or behavior. You have the interface stub for structural info (how to call the code). The spec tells you what it should return. If the spec is ambiguous about a specific expected value, write the test with a clear comment marking the assertion as "SPEC_AMBIGUOUS" so the orchestrator can flag it.
 
 Write the complete test file to the specified path. Follow the project's existing test style exactly. Do NOT add test infrastructure (no new packages, no config changes).
 ```
@@ -251,17 +268,19 @@ Also run `mcp__ide__getDiagnostics` to catch type errors and lint issues in the
 
 ### Classify Failures
 
-For each failure, classify:
+For each failure, classify. The first question is always: **does the spec clearly define the expected behavior the test asserts?**
 
-| Classification | Action |
-|---|---|
-| **Test bug** (wrong assertion, incorrect mock, import error) | Fix autonomously — `intuition-code-writer` agent |
-| **Implementation bug, trivial** (off-by-one, missing null check, typo — 1-3 lines) | Fix directly — `intuition-code-writer` agent |
-| **Implementation bug, moderate** (logic error, missing handler — contained to one file) | Fix — `intuition-code-writer` agent with full diagnosis |
-| **Implementation bug, complex** (multi-file structural issue) | Escalate to user |
-| **Fix would violate [USER] decision** | STOP — escalate to user immediately |
-| **Fix would violate [SPEC] decision** | Note the conflict, proceed with fix (specialist had authority) |
-| **Fix touches files outside build_report scope** | Escalate to user (scope creep) |
+| Classification | How to identify | Action |
+|---|---|---|
+| **Test bug** (wrong assertion, incorrect mock, import error) | Test doesn't match the spec it claims to test, or has a structural error | Fix autonomously — `intuition-code-writer` agent |
+| **Spec Violation** (implementation disagrees with spec) | Test asserts spec-defined behavior, implementation returns something different, and the spec is clear and unambiguous | Escalate to user: "Test [name] expects [spec behavior] per [acceptance criterion / blueprint spec], but implementation returns [actual]. Is the spec wrong or the code?" Options: "Fix the code" / "Spec was wrong — update test" / "I'll investigate" |
+| **Spec Ambiguity** (spec underspecified, test assertion is a guess) | Test is marked SPEC_AMBIGUOUS, or the spec doesn't define the expected value precisely enough to write a deterministic assertion | Escalate to user: "Spec doesn't clearly define expected behavior for [scenario]. The code does [X]. Is that correct?" Options: "Yes, that's correct — lock it in" / "No, it should do [other]" / "Skip this test" |
+| **Implementation bug, trivial** (off-by-one, missing null check, typo — 1-3 lines) | Spec is clear, implementation is clearly wrong, fix is small | Fix directly — `intuition-code-writer` agent |
+| **Implementation bug, moderate** (logic error, missing handler — contained to one file) | Spec is clear, implementation is wrong, fix is contained | Fix — `intuition-code-writer` agent with full diagnosis |
+| **Implementation bug, complex** (multi-file structural issue) | Spec is clear, but fix requires architectural changes | Escalate to user |
+| **Fix would violate [USER] decision** | Any tier | STOP — escalate to user immediately |
+| **Fix would violate [SPEC] decision** | Any tier | Note the conflict, proceed with fix (specialist had authority) |
+| **Fix touches files outside build_report scope** | Any tier | Escalate to user (scope creep) |
 
 ### Decision Boundary Checking
 
@@ -311,9 +330,10 @@ Write `{context_path}/test_report.md`:
 ## Failures & Resolutions
 
 ### [Test name]
-- **Type:** [test bug / implementation bug — trivial/moderate/complex]
-- **Root cause:** [description]
-- **Resolution:** [fix applied] OR **Escalated:** [reason not fixable autonomously]
+- **Type:** [test bug / spec violation / spec ambiguity / implementation bug — trivial/moderate/complex]
+- **Spec source:** [which acceptance criterion, blueprint spec, or process_flow section defined the expected behavior]
+- **Root cause:** [description — what the spec says vs. what the implementation does]
+- **Resolution:** [fix applied] OR **Escalated:** [reason — spec violation pending user decision / ambiguity / architectural / scope creep / max retries]
 
 ## Implementation Fixes Applied
 | File | Change | Rationale |