Add ACH-enhanced deep research, upgrade research workflow

README.md

@@ -119,6 +119,7 @@ Verify with `/context-mode:ctx-doctor` (plugin install) or check MCP tools are a
 | `/devkit:refactor` | Full refactor lifecycle — analyze, plan, restructure, verify, compare |
 | `/devkit:decompose` | Goal decomposition — break into task DAG, assign agents, execute in dependency order |
 | `/devkit:audit` | Full project health audit — deps, vulnerabilities, licenses, lint, security |
+| `/devkit:deep-research` | ACH-enhanced deep research — competing hypotheses, directed disconfirmation, evidence matrix, sensitivity analysis |
 | `/devkit:status` | Health check — installed CLIs, available agents, ready commands |
 
 ### Self-Improvement Loops (Claude-only)
@@ -174,7 +175,8 @@ These replace slash commands. Ask naturally and the skill fires:
 | `devkit:doc-gen` | "document this module", "generate API docs", "write docs for" |
 | `devkit:changelog` | "generate a changelog", "release notes", "what changed since" |
 | `devkit:onboard` | "explain this codebase", "help me understand the architecture", "onboard" |
-| `devkit:research` | "research X", "deep dive on", "compare approaches for" |
+| `devkit:research` | "research X", "compare approaches for", "investigate options" |
+| `devkit:deep-research` | "deep research", "validate this", "make sure this is right", "rigorous analysis" |
 | `devkit:scrape` | "scrape this URL", "fetch content from", "extract from this page" |
 
 ### Coding Principles
@@ -309,7 +311,7 @@ devkit/
 │   └── plugin.json          # Plugin metadata (name, version, author)
 ├── ROADMAP.md               # Implemented features and future plans
 ├── PREFERENCES.md           # Agent behavior guidelines
-├── commands/                # 20 slash commands (tab-completable)
+├── commands/                # 21 slash commands (tab-completable)
 │   ├── tri-*.md             # Multi-agent dispatch (5)
 │   ├── self-*.md            # Self-improvement loops (5)
 │   ├── pr-ready.md          # PR preparation pipeline
@@ -322,7 +324,7 @@ devkit/
 │   ├── audit.md             # Project health audit
 │   ├── repo-map.md          # AST-based symbol index
 │   └── status.md            # Health check
-├── skills/                  # 15 context-activated skills
+├── skills/                  # 16 context-activated skills
 │   ├── executing/SKILL.md   # Principle: methodical execution
 │   ├── clean-code/SKILL.md  # Principle: readability
 │   ├── dry/SKILL.md         # Principle: don't repeat yourself
@@ -335,7 +337,9 @@ devkit/
 │   ├── doc-gen/SKILL.md     # Auto: "document this module"
 │   ├── test-gen/SKILL.md    # Auto: "write tests for X"
 │   ├── onboard/SKILL.md     # Auto: "explain this codebase"
-│   ├── research/SKILL.md    # Auto: "research X"
+│   ├��─ research/SKILL.md    # Auto: "research X"
+│   ├── deep-research/SKILL.md # Auto: "deep research", ACH pipeline
+│   ├── scratchpad/SKILL.md  # Iteration memory protocol
 │   └── scrape/SKILL.md      # Auto: "scrape this URL"
 ├── agents/                  # 6 agents
 │   ├── reviewer.md          # Opus, worktree isolation
@@ -356,7 +360,7 @@ devkit/
 │   ├── lang-review.sh       # Language-aware code quality (Go/TS/Rust/Python/Shell)
 │   ├── subagent-stop.sh     # Subagent work verification
 │   └── stop-gate.sh         # Consolidated quality gate (cross-domain + vet/lint)
-├── workflows/               # 12 YAML workflow definitions
+├── workflows/               # 13 YAML workflow definitions
 ├── presets/                  # Reserved for future use
 ├── .github/workflows/       # CI/CD
 │   ├── ci.yml               # Build + test + vet on push/PR

ROADMAP.md

@@ -2,8 +2,8 @@
 
 ## Implemented
 
-- **20 slash commands** — Lifecycle workflows, self-improvement loops, multi-agent dispatch, project health audit, post-PR monitoring, AST repo mapping
-- **15 context-activated skills** — 6 auto-trigger workflows (test-gen, doc-gen, changelog, onboard, research, scrape) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows) + 1 iteration memory (scratchpad)
+- **21 slash commands** — Lifecycle workflows, self-improvement loops, multi-agent dispatch, project health audit, post-PR monitoring, AST repo mapping
+- **16 context-activated skills** — 7 auto-trigger workflows (test-gen, doc-gen, changelog, onboard, research, deep-research, scrape) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows) + 1 iteration memory (scratchpad)
 - **6 agents** — Scoped tool access, worktree isolation, model assignment
 - **10 hooks** — Safety (destructive command blocking, edit-time security patterns, PR gate), observability (audit trail, slop detection, post-validation, subagent verification, language-aware code review), optimization (RTK token compression)
 - **Graceful degradation** — tri:* commands work with 1-3 agents depending on installed CLIs
@@ -12,7 +12,7 @@
 - **Early-exit conditions** — Self-improvement loops stop when goal is met, not just at max iterations
 - **Token budget guidance** — Per-command budget recommendations with model downgrade patterns
 - **RTK token optimization** — Optional PreToolUse hook compresses Bash output via RTK (60-90% savings)
-- **12 YAML workflows** — Portable workflow definitions (feature, bugfix, refactor, research, self-*, tri-*)
+- **13 YAML workflows** — Portable workflow definitions (feature, bugfix, refactor, research, deep-research, self-*, tri-*)
 - **Separate marketplace** — Multi-plugin marketplace at `5uck1ess/marketplace`
 - **Companion ecosystem** — Evaluated official marketplace, documented holistic setup with 7 complementary plugins
 - **Hypothesis-driven perf** — Evidence gathering, ranked hypotheses, one-at-a-time testing replaces blind benchmark loops
@@ -23,7 +23,7 @@
 - **Iteration scratchpads** — Persistent memory across loop iterations to prevent repeated failures
 - **Cross-domain dirty-bit enforcement** — Blocks completion without test evidence per domain
 - **Language-universal hooks** — Consolidated language-specific hooks into `lang-review.sh` with Go, TypeScript, Rust, Python, and Shell support
-- **Hook consolidation** — Merged 14 hooks into 9, reduced per-edit shell processes from 7 to 4
+- **Hook consolidation** — Merged 14 hooks into 10, reduced per-edit shell processes from 7 to 4
 
 ## Retired
 
@@ -34,6 +34,6 @@ Items below were on the roadmap but determined to be unnecessary — either alre
 | Stop hook redesign | Still fires every turn, but exits early with `approve` when no files are changed — near-instant on clean trees, so the performance concern is moot. Revisit only if it causes measurable latency. |
 | Cost event hooks | Budget enforcement already exists in the Go engine via `overBudget()` + `addCost()` callbacks with hard limits |
 | Execution registry | Step tracking already handled by SQLite via `lib.DB` with status, cost, and timing per step |
-| Preset library | The 12 YAML workflows and 15 skills already serve this purpose |
+| Preset library | The 13 YAML workflows and 16 skills already serve this purpose |
 | Framework-specific review checklists | `lang-review.sh` covers language-level patterns; framework-specific rules are better added per-project via hookify |
 | Conditional hook firing | Hooks already self-filter internally (extension checks, changed-file checks); a generic condition system adds complexity for no current need |

commands/deep-research.md

@@ -0,0 +1,130 @@
+---
+description: ACH-enhanced deep research — perspective discovery, competing hypotheses, directed disconfirmation, evidence matrix, sensitivity analysis.
+---
+
+# Deep Research
+
+Rigorous research for complex or high-stakes questions where correctness matters. Uses Analysis of Competing Hypotheses (ACH) to actively disprove answers rather than just confirming them.
+
+Use regular `/devkit:research` for quick lookups. Use this when:
+- The answer has real consequences (architecture decisions, tool selection, security)
+- Multiple conflicting sources exist
+- You need confidence calibration, not just an answer
+- The user says "deep research", "validate", "make sure this is right"
+
+## Step 0: Harness Detection
+
+```bash
+if command -v devkit >/dev/null 2>&1; then
+  echo "Go harness detected — delegating to devkit workflow deep-research."
+  devkit workflow deep-research "{input}"
+  exit 0
+fi
+```
+
+## Step 1: Clarify
+
+```
+The user wants to deep-research: {input}
+
+Use AskUserQuestion to clarify:
+- What specifically are we trying to learn?
+- What constraints matter?
+- What would a wrong answer cost?
+- Any sources they already know about?
+
+Restate the research question precisely.
+```
+
+## Step 2: Discover Perspectives
+
+Search for 2-3 overview articles on the topic. Fetch with Jina Reader (`WebFetch https://r.jina.ai/{url}`). Extract major schools of thought, key voices, known debates. Summarize immediately — do not carry raw content forward.
+
+## Step 3: Decompose into Sub-Questions
+
+Break the question into 5-8 sub-questions with explicit retrieval goals and perspective labels. At least 2 queries must seek **disconfirming** evidence.
+
+## Step 4: Search (Parallel Fan-Out)
+
+**[PARALLEL]** Launch searches concurrently using the `researcher` agent (max 3 per batch):
+
+```
+Task: Execute web search for sub-question.
+Agent: researcher
+Input: Query + Goal + Perspective
+```
+
+## Budget
+
+- **Token budget:** ~400k tokens.
+- **Early exit:** Only if the question turns out trivial after perspective discovery.
+
+## Step 5: Summarize and Extract Claims
+
+Fetch top 5-8 URLs with Jina Reader. Extract atomic claims (subject-predicate-object). Summarize immediately. Aim for 3-8 claims per source.
+
+## Step 6: Generate Competing Hypotheses
+
+Generate 2-4 mutually exclusive hypotheses. Include at least one contrarian hypothesis.
+
+## Step 7: Directed Disconfirmation
+
+For EACH hypothesis, search specifically for evidence that would DISPROVE it. This is the critical ACH step — you're trying to kill each hypothesis, not confirm it.
+
+## Step 8: Build Evidence Matrix
+
+```
+| Evidence | H1 | H2 | H3 |
+|----------|----|----|-----|
+| Claim [source] | CC | I | N |
+
+CC=Strongly Consistent, C=Consistent, N=Neutral, I=Inconsistent, II=Strongly Inconsistent
+```
+
+Score by FEWEST inconsistencies (not most consistencies).
+
+## Step 9: Sensitivity Check
+
+Identify linchpin evidence — what single fact, if wrong, would change the conclusion?
+
+## Step 10: Self-Critique
+
+Review for: genuine disconfirmation effort, missed perspectives, source over-weighting, fairness to opposing views. One more search round if gaps found.
+
+## Step 11: Synthesize
+
+```
+## Deep Research: {question}
+
+### Direct Answer
+{answer with confidence: HIGH / MEDIUM / LOW}
+
+### Competing Hypotheses
+{for each: statement, supporting evidence, disconfirming evidence, status}
+
+### Evidence Matrix Summary
+{matrix or prose summary}
+
+### Key Findings
+{CONFIRMED / CONTESTED / UNCORROBORATED claims with sources}
+
+### Sensitivity Analysis
+{linchpin evidence, confidence fragility}
+
+### What Would Change This Conclusion
+{specific evidence that would flip the answer}
+
+### Recommendation
+{what to do, why, with calibrated confidence}
+```
+
+## Rules
+
+- Perspectives first — ground queries in real viewpoints
+- Disconfirm > confirm — try to KILL hypotheses
+- Summarize immediately — no raw content carried forward
+- Evidence matrix is mandatory
+- Sensitivity check is mandatory
+- Self-critique before output
+- Cite everything
+- Be honest about uncertainty