Research

Research Skill

Quick Ref: Deep codebase exploration with multi-angle analysis. Output: .agents/research/*.md

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

CLI dependencies: ao (knowledge injection — optional). If ao is unavailable, skip prior knowledge search and proceed with direct codebase exploration.

Flags

Execution Steps

Given /research <topic> [--auto]:

Step 1: Create Output Directory

mkdir -p .agents/research

Step 2: Check Prior Art

First, search and inject existing knowledge (if ao available):

# Pull relevant prior knowledge for this topic
ao lookup --query "<topic>" --limit 5 2>/dev/null || \
  ao search "<topic>" 2>/dev/null || \
  echo "ao not available, skipping knowledge search"

Apply retrieved knowledge (mandatory when results returned):

If ao returns relevant learnings or patterns, do NOT just load them as passive context. For each returned item: 1. Check: does this learning apply to the current research topic? (answer yes/no) 2. If yes: note how it shapes your research direction — what questions does it answer? what areas does it warn about? 3. Cross-reference prior findings against new discoveries in your research output 4. Cite applicable learnings by filename in the research document's Findings section

After applying, record each citation:

ao metrics cite "<learning-path>" --type applied 2>/dev/null || true

Also look for:

• Prior research on this topic or related topics
• Known patterns or anti-patterns
• Lessons learned from similar investigations

Search ALL local knowledge locations by content (not just filename):

Use Grep to search every knowledge directory for the topic. This catches learnings from /post-mortem, brainstorms, and plans — not just research artifacts.

# Search all knowledge locations by content
for dir in research learnings knowledge patterns retros plans brainstorm; do
  grep -r -l -i "<topic>" .agents/${dir}/ 2>/dev/null
done

# Search global patterns (cross-repo knowledge)
grep -r -l -i "<topic>" ~/.claude/patterns/ 2>/dev/null

If matches are found, read the relevant files with the Read tool before proceeding to exploration. Prior knowledge prevents redundant investigation.

Step 2.5: Pre-Flight — Detect Spawn Backend

Before launching the explore agent, detect which backend is available:

1. Check if spawn_agent is available → log "Backend: codex-sub-agents" 2. Else check if TeamCreate is available → log "Backend: claude-native-teams" 3. Else check if skill tool is read-only (OpenCode) → log "Backend: opencode-subagents" 4. Else check if Task is available → log "Backend: background-task-fallback" 5. Else → log "Backend: inline (no spawn available)"

Record the selected backend — it will be included in the research output document for traceability.

Read the matching backend reference for concrete tool call examples:

• Shared Claude feature contract → skills/shared/references/claude-code-latest-features.md
• Local mirrored contract for runtime-local reads → references/claude-code-latest-features.md
• Codex → references/backend-codex-subagents.md
• Claude Native Teams → references/backend-claude-teams.md
• Background Tasks → references/backend-background-tasks.md
• Inline → references/backend-inline.md

Effort and Session Hints

• Set effort to low for explore agents — research is breadth-first scanning, not deep reasoning.
• Use --from-pr <url> to scope research to a specific PR's changed files when investigating PR-related topics.

Step 3: Launch Explore Agent

YOU MUST DISPATCH AN EXPLORATION AGENT NOW. Select the backend using capability detection:

Backend Selection (MANDATORY)

1. If spawn_agent is available → Codex sub-agent 2. Else if TeamCreate is available → Claude native team (Explore agent) 3. Else if skill tool is read-only (OpenCode) → OpenCode subagent — task(subagent_type="explore", description="Research: <topic>", prompt="<explore prompt>") 4. Else → Background task fallback

Exploration Prompt (all backends)

Use this prompt for whichever backend is selected. The exploration uses iterative retrieval (see references/iterative-retrieval.md): start broad, score relevance, extract new search terms from high-relevance files, and repeat for up to 3 cycles.

Thoroughly investigate: <topic>

Use iterative retrieval: after each discovery tier, score results 0-1 for relevance.
From files scoring 0.5+, extract new search terms (function names, imports, config keys).
Use extracted terms in subsequent tiers. Max 3 refinement cycles.

Discovery tiers (execute in order, skip if source unavailable):

Tier 1 — Code-Map (fastest, authoritative):
  Read docs/code-map/README.md → find <topic> category
  Read docs/code-map/{feature}.md → get exact paths and function names
  Skip if: no docs/code-map/ directory

Tier 2 — Semantic Search (conceptual matches):
  mcp__smart-connections-work__lookup query="<topic>" limit=10
  Skip if: MCP not connected

Tier 2.5 — Git History (recent changes and decision context):
  git log --oneline -30 -- <topic-related-paths>   # scoped to relevant paths, cap 30 lines
  git log --all --oneline --grep="<topic>" -10      # cap 10 matches
  git blame <key-file> | grep -i "<topic>" | head -20  # cap 20 lines
  Skip if: not a git repo, no relevant history, or <topic> too broad (>100 matches)
  NEVER: git log on full repo without -- path filter (same principle as Tier 3 scoping)
  NOTE: This is git commit history, not session history. For session/handoff history, use /recover.

Tier 3 — Scoped Search (keyword precision):
  Grep("<topic>", path="<specific-dir>/")   # ALWAYS scope to a directory
  Glob("<specific-dir>/**/*.py")            # ALWAYS scope to a directory
  NEVER: Grep("<topic>") or Glob("**/*.py") on full repo — causes context overload

Tier 4 — Source Code (verify from signposts):
  Read files identified by Tiers 1-3 (including git history leads from Tier 2.5)
  Use function/class names, not line numbers

Tier 5 — Prior Knowledge (may be stale):
  Search ALL .agents/ knowledge dirs by content:
    for dir in research learnings knowledge patterns retros plans brainstorm; do
      grep -r -l -i "<topic>" .agents/${dir}/ 2>/dev/null
    done
  Read matched files. Cross-check findings against current source.

Tier 6 — External Docs (last resort):
  WebSearch for external APIs or standards
  Only when Tiers 1-5 are insufficient

Return a detailed report with:
- Key files found (with paths)
- How the system works
- Important patterns or conventions
- Any issues or concerns

Cite specific file:line references for all claims.

Spawn Research Agents

If your runtime supports spawning parallel subagents, spawn one or more research agents with the exploration prompt. Each agent explores independently and writes findings to .agents/research/.

If no multi-agent capability is available, perform the exploration inline in the current session using file reading, grep, and glob tools directly.

Step 4: Validate Research Quality (mandatory in auto mode)

For thorough research, perform quality validation:

Auto mode enforcement: When --auto is set, quality validation is mandatory. If depth rating < 2 for any critical area (Step 4b), emit WARN and log to .agents/research/quality-warning.md. In interactive mode, this step remains optional.

4a. Coverage Validation

Check: Did we look everywhere we should? Any unexplored areas?

• List directories/files explored
• Identify gaps in coverage
• Note areas that need deeper investigation

4b. Depth Validation

Check: Do we UNDERSTAND the critical parts? HOW and WHY, not just WHAT?

• Rate depth (0-4) for each critical area
• Flag areas with shallow understanding
• Identify what needs more investigation

4c. Gap Identification

Check: What DON'T we know that we SHOULD know?

• List critical gaps
• Prioritize what must be filled before proceeding
• Note what can be deferred

4d. Assumption Challenge

Check: What assumptions are we building on? Are they verified?

• List assumptions made
• Flag high-risk unverified assumptions
• Note what needs verification

Step 5: Synthesize Findings

After the Explore agent and validation swarm return, write findings to: .agents/research/YYYY-MM-DD-<topic-slug>.md

Use this format:

---
id: research-YYYY-MM-DD-<topic-slug>
type: research
date: YYYY-MM-DD
---

# Research: <Topic>

**Backend:** <codex-sub-agents | claude-native-teams | background-task-fallback | inline>
**Scope:** <what was investigated>

## Summary
<2-3 sentence overview>

## Key Files
| File | Purpose |
|------|---------|
| path/to/file.py | Description |

## Findings
<detailed findings with file:line citations>

## Recommendations
<next steps or actions>

Step 5.5: Persist Reusable Findings

After the research artifact is written, identify any reusable findings that should influence future work.

Persist only reusable findings, not transient observations, to .agents/findings/registry.jsonl using the finding-registry contract:

• include provenance fields: source.repo, source.session, source.file, source.skill
• require dedup_key, pattern, detection_question, checklist_item, applicable_when, and confidence
• keep lifecycle fields explicit: status, superseded_by, ttl_days, hit_count, last_cited
• merge by dedup_key
• use the contract's temp-file-plus-rename atomic write rule

After the registry update, if hooks/finding-compiler.sh exists, run:

bash hooks/finding-compiler.sh --quiet 2>/dev/null || true

This refreshes promoted findings and compiled prevention outputs in the same session.

Step 6: Request Human Approval (Gate 1)

Skip this step if `--auto` flag is set. In auto mode, proceed directly to Step 7.

USE AskUserQuestion tool:

Tool: AskUserQuestion
Parameters:
  questions:
    - question: "Research complete. Approve to proceed to planning?"
      header: "Gate 1"
      options:
        - label: "Approve"
          description: "Research is sufficient, proceed to /plan"
        - label: "Revise"
          description: "Need deeper research on specific areas"
        - label: "Abandon"
          description: "Stop this line of investigation"
      multiSelect: false

Wait for approval before reporting completion.

Step 7: Report to User

Tell the user: 1. What you found 2. Where the research doc is saved 3. Gate 1 approval status 4. Next step: /plan to create implementation plan

Key Rules

• Actually dispatch the Explore agent - don't just describe doing it
• Scope searches - use the topic to narrow file patterns
• Cite evidence - every claim needs file:line
• Write output - research must produce a .agents/research/ artifact

Thoroughness Levels

Include in your Explore agent prompt:

• "quick" - for simple questions
• "medium" - for feature exploration
• "very thorough" - for architecture/cross-cutting concerns

For onboarding-style research ("what does this do?", new repo orientation), follow references/onboarding-methodology.md for the phased docs-first walk and reusable mental-model template. When the question reduces to "what happens when <event> arrives?", trace one path end-to-end using references/data-flow-from-entry-points.md.

Examples

Investigate Authentication System

User says: /research "authentication system"

What happens: 1. Agent searches knowledge base for prior auth research 2. Explore agent investigates via Code-Map, Grep, and file reading 3. Findings synthesized with file:line citations 4. Output written to .agents/research/2026-02-13-authentication-system.md

Result: Detailed report identifying auth middleware location, session handling, and token validation patterns.

Quick Exploration of Cache Layer

User says: /research "cache implementation"

What happens: 1. Agent uses Glob to find cache-related files 2. Explore agent reads key files and summarizes current state 3. No prior research found, proceeds with fresh exploration 4. Output written to .agents/research/2026-02-13-cache-implementation.md

Result: Summary of cache strategy, TTL settings, and eviction policies with file references.

Deep Dive into Payment Flow

User says: /research "payment processing flow"

What happens: 1. Agent loads prior payment research from knowledge base 2. Explore agent traces flow through multiple services 3. Identifies integration points and error handling 4. Output written with cross-service file citations

Result: End-to-end payment flow diagram with file paths and critical decision points.

Troubleshooting

Reference Documents

• references/research.feature — Executable spec: prior-art-first, explore-agent + iterative retrieval, cited .agents/research/ artifact, Gate-1 unless --auto (soc-qk4b)

• references/iterative-retrieval.md
• references/deep-research-mcp.md
• references/backend-background-tasks.md
• references/backend-claude-teams.md
• references/backend-codex-subagents.md
• references/backend-inline.md
• references/claude-code-latest-features.md
• references/context-discovery.md
• references/data-flow-from-entry-points.md
• references/document-template.md
• references/failure-patterns.md
• references/onboarding-methodology.md
• references/ralph-loop-contract.md
• references/source-discovery-and-pattern-extraction.md
• references/vibe-methodology.md
• ../shared/references/backend-background-tasks.md
• ../shared/references/backend-claude-teams.md
• ../shared/references/backend-codex-subagents.md
• ../shared/references/backend-inline.md
• ../shared/references/claude-code-latest-features.md
• ../shared/references/ralph-loop-contract.md
• references/codebase-archaeology.md — Systematic codebase exploration for onboarding
• references/software-research.md — Research tools via source code, GitHub, and web

Backend: Background Tasks (Fallback)

Concrete tool calls for spawning agents using Task(run_in_background=true). This is the last-resort fallback when neither Codex sub-agents nor Claude native teams are available.

When detected: Task tool is available but TeamCreate and spawn_agent are not.

Limitations:

• Fire-and-forget — no messaging, no redirect, no scope adjustment
• No inter-agent communication
• No debate mode (R2 requires messaging)
• No retry (must re-spawn from scratch)
• No graceful shutdown (only TaskStop, which is lossy)

---

Spawn: Background Agents

Spawn agents with Task(run_in_background=true). Each call returns a task_id for later polling.

Council Judges

Task(
  subagent_type="general-purpose",
  run_in_background=true,
  prompt="You are judge-1.\n\nYour perspective: Correctness & Completeness\n\n<PACKET>\n...\n</PACKET>\n\nWrite your verdict to .agents/council/2026-02-17-auth-judge-1.md\nThis is your ONLY output channel — there is no messaging.",
  description="Council judge-1"
)
# Returns: task_id="abc-123"

Task(
  subagent_type="general-purpose",
  run_in_background=true,
  prompt="You are judge-error-paths.\n\nYour perspective: Error Paths & Edge Cases\n\n<PACKET>...</PACKET>\n\nWrite your verdict to .agents/council/2026-02-17-auth-judge-error-paths.md",
  description="Council judge-error-paths"
)
# Returns: task_id="def-456"

Both Task calls go in the same message — they run in parallel.

Swarm Workers

Task(
  subagent_type="general-purpose",
  run_in_background=true,
  prompt="You are worker-3.\n\nYour Assignment: Task #3: Add password hashing\n...\n\nWrite result to .agents/swarm/results/3.json\nDo NOT run git add/commit/push.",
  description="Swarm worker-3"
)

Research Explorers

Task(
  subagent_type="Explore",
  run_in_background=true,
  prompt="Thoroughly investigate: authentication patterns...\n\nWrite findings to .agents/research/2026-02-17-auth.md",
  description="Research explorer"
)

---

Wait: Poll for Completion

Background tasks have no messaging. Poll with TaskOutput.

TaskOutput(task_id="abc-123", block=true, timeout=120000)
TaskOutput(task_id="def-456", block=true, timeout=120000)

Or non-blocking check:

TaskOutput(task_id="abc-123", block=false, timeout=5000)

After `TaskOutput` returns, verify the agent wrote its result file:

Read(".agents/council/2026-02-17-auth-judge-1.md")

Timeout behavior: If timeout expires, TaskOutput returns with a timeout status — the agent may still be running. Recovery: 1. Check result file — agent may have written it but not finished cleanly 2. If result file exists → use it, TaskStop the agent 3. If no result file → agent failed silently. For council: proceed with N-1 verdicts, note in report. For swarm: add task back to retry queue, re-spawn a fresh agent. 4. Never assume TaskOutput completion means the result file was written — always verify

Fallback: If background tasks fail despite detection, fall back to inline mode. See backend-inline.md.

---

No Messaging

Background tasks cannot receive messages. This means:

• No debate R2 — judges get one round only
• No retry — if validation fails, re-spawn a new agent from scratch
• No scope adjustment — the prompt is final at spawn time

---

Cleanup

Background tasks self-terminate when done. For stuck tasks:

TaskStop(task_id="abc-123")

This is lossy — partial work may be lost.

---

Key Rules

1. Filesystem is the only communication channel — agents write files, lead reads files 2. No messaging = no debate — --debate is unavailable with this backend 3. No retry = must re-spawn — failed agents get a fresh Task call, not a message 4. Always check result files — TaskOutput completion doesn't guarantee the agent wrote its file 5. Prefer native teams — this backend is strictly inferior; use it only as last resort

Backend: Claude Native Teams

Concrete tool calls for spawning agents using Claude Code native teams (TeamCreate + SendMessage + shared TaskList).

When detected: TeamCreate tool is available in your tool list.

---

Pre-Flight: Confirm Modern Claude Features

Before spawning teammates, verify feature readiness:

1. claude agents succeeds (custom agents discoverable) 2. Teammate profiles for write tasks declare isolation: worktree 3. Long-running teammates prefer background: true 4. Hooks include worktree lifecycle coverage (WorktreeCreate, WorktreeRemove) and config auditing (ConfigChange) where policy requires it

For canonical feature details, read: skills/shared/references/claude-code-latest-features.md.

---

Setup: Create Team

Every spawn session starts by creating a team. One team per wave (fresh context = Ralph Wiggum preserved; see skills/shared/references/ralph-loop-contract.md).

TeamCreate(team_name="council-20260217-auth", description="Council validation of auth module")

TeamCreate(team_name="swarm-1739812345-w1", description="Wave 1: parallel implementation")

Naming conventions:

• Council: council-YYYYMMDD-<target>
• Swarm: swarm-<epoch>-w<wave>
• Crank: delegates to swarm naming

Leader Contract (Native Teams)

Claude teams are leader-first orchestration:

1. One lead creates the team and assigns all work. 2. Teammates never self-assign from shared tasks. 3. Teammates report to lead via short SendMessage signals. 4. Lead reads result artifacts from disk, validates, and decides retries/escalation.

Recommended signal envelope (single-line JSON, under 100 tokens):

{"type":"completion|blocked|help_request","agent":"worker-3","task":"3","detail":"short status","artifact":".agents/swarm/results/3.json"}

completion: task finished, artifact written. blocked: cannot proceed safely. help_request: teammate needs coordination or scope clarification.

Peer Messaging (Allowed, Lead-Controlled)

Native teams support direct teammate-to-teammate messaging. Use this only for coordination handoffs; keep messages thin and always copy the lead in follow-up summaries.

worker-2 -> worker-5: "Need auth schema constant name; please confirm from src/auth/schema.ts"
worker-5 -> lead: "Resolved peer question for worker-2; no scope change."

---

Spawn: Create Workers/Judges

After TeamCreate, spawn each agent with Task(team_name=..., name=...). All agents in a wave spawn in parallel (single message, multiple tool calls).

Council Judges (parallel spawn)

Task(
  subagent_type="general-purpose",
  team_name="council-20260217-auth",
  name="judge-1",
  prompt="You are judge-1 on team council-20260217-auth.\n\nYour perspective: Correctness & Completeness\n\n<PACKET>\n...\n</PACKET>\n\nWrite your verdict to .agents/council/2026-02-17-auth-judge-1.md\nThen send a SHORT completion signal to the team lead (under 100 tokens).\nDo NOT include your full analysis in the message — the lead reads your file.",
  description="Council judge-1"
)

Task(
  subagent_type="general-purpose",
  team_name="council-20260217-auth",
  name="judge-error-paths",
  prompt="You are judge-error-paths on team council-20260217-auth.\n\nYour perspective: Error Paths & Edge Cases\n\n<PACKET>\n...\n</PACKET>\n\nWrite your verdict to .agents/council/2026-02-17-auth-judge-error-paths.md\nThen send a SHORT completion signal to the team lead (under 100 tokens).",
  description="Council judge-error-paths"
)

Both Task calls go in the same message — they spawn in parallel.

Swarm Workers (parallel spawn)

Task(
  subagent_type="general-purpose",
  team_name="swarm-1739812345-w1",
  name="worker-3",
  prompt="You are worker-3 on team swarm-1739812345-w1.\n\nYour Assignment: Task #3: Add password hashing\n<description>...</description>\n\nInstructions:\n1. Execute your task — create/edit files as needed\n2. Write result to .agents/swarm/results/3.json\n3. Send a SHORT signal to team lead (under 100 tokens)\n4. Do NOT run git add/commit/push — the lead commits\n\nRESULT FORMAT:\n{\"type\":\"completion\",\"issue_id\":\"3\",\"status\":\"done\",\"detail\":\"one-line summary\",\"artifacts\":[\"path/to/file\"]}",
  description="Swarm worker-3"
)

Task(
  subagent_type="general-purpose",
  team_name="swarm-1739812345-w1",
  name="worker-5",
  prompt="You are worker-5 on team swarm-1739812345-w1.\n\nYour Assignment: Task #5: Create login endpoint\n...",
  description="Swarm worker-5"
)

Research Explorers (read-only)

Task(
  subagent_type="Explore",
  team_name="research-20260217-auth",
  name="explorer-1",
  prompt="Thoroughly investigate: authentication patterns in this codebase\n\n...",
  description="Research explorer"
)

Use subagent_type="Explore" for read-only research agents. Use "general-purpose" for agents that need to write files.

---

Wait: Receive Completion Signals

Workers/judges send completion signals via SendMessage. These are automatically delivered to the team lead — no polling needed.

When a teammate finishes, their message appears as a new conversation turn. The lead reads result files from disk, NOT from message content.

# Teammate message arrives automatically:
# "judge-1: Done. Verdict: WARN, confidence: HIGH. File: .agents/council/2026-02-17-auth-judge-1.md"

# Lead reads the file for full details:
Read(".agents/council/2026-02-17-auth-judge-1.md")

Timeout handling (default: 120s per round, 90s for debate R2):

If a teammate goes idle without sending a completion signal: 1. Check their result file — they may have written it but failed to message 2. If result file exists → read it and proceed (the message was the only thing missing) 3. If no result file → the agent failed silently. Recovery: proceed with N-1 judges/workers and note the failure in the report. For swarm workers, add the task back to the retry queue. 4. Never wait indefinitely — after the timeout, move on

See skills/council/references/cli-spawning.md for timeout configuration (COUNCIL_TIMEOUT, COUNCIL_R2_TIMEOUT).

Fallback: If native teams fail at runtime despite passing detection (e.g., TeamCreate succeeds but Task spawning fails), fall back to background tasks. See backend-background-tasks.md.

---

Message: Debate R2 / Retry

Send messages to specific teammates using SendMessage. Teammates wake from idle when messaged.

Council Debate R2

SendMessage(
  type="message",
  recipient="judge-1",
  content="DEBATE ROUND 2\n\nOther judges' verdicts:\n- judge-error-paths: FAIL (HIGH confidence) — file: .agents/council/2026-02-17-auth-judge-error-paths.md\n\nRead the other judge's file. Revise your assessment considering their perspective.\nWrite your R2 verdict to .agents/council/2026-02-17-auth-judge-1-r2.md\nThen send a completion signal.",
  summary="R2 debate instructions for judge-1"
)

R2 timeout (default: 90s): If a judge doesn't respond to R2 within COUNCIL_R2_TIMEOUT, use their R1 verdict for consolidation. See skills/council/references/debate-protocol.md for full timeout handling.

Swarm Worker Retry

SendMessage(
  type="message",
  recipient="worker-3",
  content="Validation failed: pytest tests/test_auth.py returned exit code 1.\nFix the failing tests and rewrite your result to .agents/swarm/results/3.json",
  summary="Retry worker-3: test failure"
)

---

Cleanup: Shutdown and Delete

After consolidation/validate, shut down all teammates then delete the team.

# Shutdown each teammate
SendMessage(type="shutdown_request", recipient="judge-1", content="Council complete")
SendMessage(type="shutdown_request", recipient="judge-error-paths", content="Council complete")

# After all teammates acknowledge shutdown:
TeamDelete()

Reaper pattern: If a teammate doesn't respond to shutdown within 30s, proceed with TeamDelete() anyway.

If `TeamDelete` fails (e.g., stale members): clean up manually with rm -rf ~/.claude/teams/<team-name>/ then retry TeamDelete() to clear in-memory state.

---

Multi-Wave Pattern

For crank/swarm with multiple waves, create a new team per wave:

# Wave 1
TeamCreate(team_name="swarm-1739812345-w1", description="Wave 1")
# ... spawn workers, wait, validate, commit ...
# ... shutdown teammates ...
TeamDelete()
# If TeamDelete fails: rm -rf ~/.claude/teams/swarm-1739812345-w1/ then retry

# Wave 2 (fresh context)
TeamCreate(team_name="swarm-1739812345-w2", description="Wave 2")
# ... spawn workers for newly-unblocked tasks ...
TeamDelete()

This ensures each wave's workers start with clean context (no leftover state from prior waves).

If `TeamDelete` fails between waves, the next TeamCreate may conflict. Always verify cleanup succeeded before creating the next wave team.

---

Key Rules

1. `TeamCreate` before `Task` — tasks created before the team are invisible to teammates — Enforcement: `safety.ValidateTeamLifecycle()` (T9) 2. Pre-assign tasks before spawning — workers do NOT race-claim from TaskList — Enforcement: documentation only 3. Lead-only commits — workers write files, lead runs git add + git commit — Enforcement: `hooks/git-worker-guard.sh` (T4) 4. Thin messages — workers send <100 token signals, full results go to disk — Enforcement: `safety.ValidateMessageSize()` (T9) 5. New team per wave — fresh context, Ralph Wiggum preserved — Enforcement: `safety.ValidateTeamLifecycle()` (T9) 6. Always cleanup — TeamDelete() after every wave, even on partial failure — Enforcement: `hooks/stop-team-guard.sh` + `safety.ValidateTeamLifecycle()` (T9)

Backend: Codex Sub-Agents

Concrete tool calls for spawning agents using Codex CLI (codex exec). Used for --mixed mode cross-vendor consensus and as the primary backend when running inside a Codex session with spawn_agent.

---

Variant A: Codex CLI (from any runtime)

Used when codex CLI is available on PATH. Agents run as background shell processes.

When detected: which codex succeeds.

Spawn: Background Shell Processes

# With structured output (preferred for council judges)
Bash(
  command='codex exec -s read-only -m gpt-5.3-codex -C "$(pwd)" --output-schema skills/council/schemas/verdict.json -o .agents/council/codex-1.json "JUDGE PROMPT HERE"',
  run_in_background=true
)

# Without structured output (fallback)
Bash(
  command='codex exec --full-auto -m gpt-5.3-codex -C "$(pwd)" -o .agents/council/codex-1.md "JUDGE PROMPT HERE"',
  run_in_background=true
)

Flag order: -s/--full-auto → -m → -C → --output-schema → -o → prompt

Valid flags: --full-auto, -s, -m, -C, --output-schema, -o, --add-dir Invalid flags: -q (doesn't exist), --quiet (doesn't exist), -p as a prompt flag (in Codex CLI it means profile)

Wait: Poll Background Shell

TaskOutput(task_id="<shell-id>", block=true, timeout=120000)

Then read the output file:

Read(".agents/council/codex-1.json")

Limitations

• No messaging — Codex CLI processes are fire-and-forget
• No debate R2 with Codex judges — they produce one verdict only
• --output-schema requires additionalProperties: false at all levels
• --output-schema requires ALL properties in required array
• -s read-only + -o works — -o is CLI-level post-processing, not sandbox I/O

---

Variant B: Codex Sub-Agents (inside Codex runtime)

Used when running inside a Codex session where spawn_agent is available.

When detected: spawn_agent tool is in your tool list.

Spawn

spawn_agent(message="You are judge-1.\n\nPerspective: Correctness & Completeness\n\n<PACKET>...</PACKET>\n\nWrite verdict to .agents/council/2026-02-17-auth-judge-1.md")
# Returns: agent_id

spawn_agent(message="You are worker-3.\n\nTask: Add password hashing\n...\n\nWrite result to .agents/swarm/results/3.json")
# Returns: agent_id

Wait

wait(ids=["agent-id-1", "agent-id-2"])

Timeout: wait() blocks until completion. Set a timeout at the orchestration level (default: COUNCIL_TIMEOUT=120s). If an agent doesn't complete within the timeout, close_agent it and proceed with N-1 verdicts/workers.

Message (retry/follow-up)

send_input(id="agent-id-1", message="Validation failed: fix tests and retry")

Cleanup

close_agent(id="agent-id-1")

---

Mixed Mode (Council)

For --mixed council, spawn runtime-native judges AND Codex CLI judges in parallel:

# Claude native team judges (via TeamCreate — see backend-claude-teams.md)
Task(subagent_type="general-purpose", team_name="council-20260217-auth", name="judge-1", prompt="...", description="Judge 1")
Task(subagent_type="general-purpose", team_name="council-20260217-auth", name="judge-2", prompt="...", description="Judge 2")

# Codex CLI judges (parallel background shells)
Bash(command='codex exec -s read-only -m gpt-5.3-codex -C "$(pwd)" --output-schema skills/council/schemas/verdict.json -o .agents/council/codex-1.json "PACKET"', run_in_background=true)
Bash(command='codex exec -s read-only -m gpt-5.3-codex -C "$(pwd)" --output-schema skills/council/schemas/verdict.json -o .agents/council/codex-2.json "PACKET"', run_in_background=true)

All four spawn in the same message — maximum parallelism.

Mixed mode quorum: At least 1 judge from each vendor should respond for cross-vendor consensus. If all judges from one vendor fail, proceed as single-vendor council and note the degradation in the report.

---

Key Rules

1. Pre-flight check: which codex before attempting Codex CLI spawning 2. Model availability: gpt-5.3-codex requires API account — fall back to gpt-4o if unavailable 3. Flag order matters — agents copy examples exactly 4. `codex review` is a different command with different flags — do not conflate with codex exec 5. No debate with Codex judges — they produce one verdict, Codex CLI has no messaging

Backend: Inline (No Spawn Available)

Degraded single-agent mode when no multi-agent primitives are detected. The current agent performs all work sequentially in its own context.

When detected: No spawn_agent, no TeamCreate, no Task tool available — or --quick flag was explicitly set.

---

Council: Single Inline Judge

Instead of spawning parallel judges, the lead evaluates from each perspective sequentially:

1. Build the context packet (same as multi-agent mode)
2. For each perspective:
   a. Adopt the perspective mentally
   b. Write findings to .agents/council/YYYY-MM-DD-<target>-<perspective>.md
3. Synthesize into final report

Output format is identical — same file paths, same verdict schema. Downstream consumers (consolidation, report) don't know it was inline.

No debate available — debate requires messaging between agents.

---

Swarm: Sequential Execution

Instead of parallel workers, execute each task sequentially:

1. TaskList() — find unblocked tasks
2. For each unblocked task (in order):
   a. Execute the task directly
   b. Write result to .agents/swarm/results/<task-id>.json
   c. TaskUpdate(taskId="<id>", status="completed")
3. Check for newly-unblocked tasks
4. Repeat until all tasks complete

Same result files, same validation — just sequential.

Error handling: If a task fails mid-execution: 1. Write failure result to .agents/swarm/results/<task-id>.json with "status": "blocked" 2. Check if downstream tasks depend on it (blockedBy) 3. Skip blocked downstream tasks, mark as skipped 4. Continue with independent tasks that don't depend on the failed one

---

Research: Inline Exploration

Instead of spawning an Explore agent, perform the tiered search directly:

1. Read docs/code-map/ if present
2. Grep/Glob for relevant files
3. Read key files
4. Write findings to .agents/research/YYYY-MM-DD-<topic>.md

---

Key Rules

1. Same output format — inline mode writes the same files as multi-agent mode 2. Same validation — all checks still apply 3. Slower but functional — no parallelism, but all skill capabilities preserved (except debate) 4. Inform the user — log "Running in inline mode (no multi-agent backend detected)"

Claude Code Latest Features Contract

This document is the shared source of truth for Claude Code feature usage across AgentOps skills.

Baseline

• Target Claude Code release family: 2.1.x
• Last verified against upstream changelog: 2.1.75
• Changelog source: https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md

Current Feature Set We Rely On

1. Core Slash Commands

Skills and docs should assume these commands exist and prefer them over legacy naming:

• /agents
• /hooks
• /permissions
• /memory
• /mcp
• /output-style
• /effort — set model effort level (low/medium/high). Opus 4.6 defaults to medium.
• /color — set prompt-bar color per session (useful for distinguishing parallel sessions)

Reference: https://code.claude.com/docs/en/slash-commands

2. Agent Definitions

For custom teammates in .claude/agents/*.md, use modern frontmatter fields where applicable:

• model
• description
• tools
• memory (scope control)
• background: true for long-running teammates
• isolation: worktree for safe parallel write isolation

Reference: https://code.claude.com/docs/en/sub-agents

3. Worktree Isolation

When parallel workers may touch overlapping files, prefer Claude-native isolation features first:

• Session-level isolation: claude --worktree (-w)
• Agent-level isolation: isolation: worktree
• Sparse checkout: worktree.sparsePaths setting — limit worktree to relevant directories in large monorepos

If unavailable in a given runtime, fall back to manual git worktree orchestration.

Reference: changelog 2.1.49, 2.1.50, and 2.1.75.

4. Hooks and Governance Events

Hooks-based workflows should include modern event coverage:

• WorktreeCreate
• WorktreeRemove
• ConfigChange
• SubagentStop
• TaskCompleted
• TeammateIdle
• PostCompact — fires after session context compaction. Use for auto-recovery (e.g., re-inject context).
• InstructionsLoaded — fires when CLAUDE.md loads. Use for policy enforcement.

HTTP hooks: Hooks can POST JSON to a URL and receive JSON responses, in addition to shell script execution.

Use these for auditability, policy enforcement, and cleanup.

Reference: https://code.claude.com/docs/en/hooks

5. Settings Hierarchy

Skill guidance must respect settings precedence:

1. Enterprise managed policy 2. Command-line args 3. Local project settings 4. Shared project settings 5. User settings

Reference: https://code.claude.com/docs/en/settings

6. Agent Inventory Command

Use claude agents as the first CLI-level check to confirm configured teammate profiles before multi-agent runs.

Reference: changelog 2.1.50.

7. Session Management

• --from-pr <url> — start or resume a session linked to a specific GitHub PR
• --worktree (-w) — start session in an isolated git worktree

Reference: https://code.claude.com/docs/en/cli-reference

8. Tool Enhancements

• Read tool: pages parameter for PDFs — read specific page ranges (e.g., pages: "1-5"). Large PDFs (>10 pages) require this parameter.
• Bash tool: Wildcard permission patterns — Bash(npm *) or Bash(* install) for flexible auto-approval.

9. Effort Levels

The /effort command controls model reasoning depth:

• low — fast, shallow reasoning. Good for research/exploration agents.
• medium — balanced (Opus 4.6 default).
• high — deep reasoning. Good for implementation and complex debugging.

Skill recommendation: set effort per agent role — low for judges/explorers, high for implementors.

Skill Authoring Rules

1. Do not reference deprecated permission command names (/allowed-tools, /approved-tools). 2. Multi-agent skills (council, swarm, research, crank, codex-team) must explicitly point to this contract. 3. Prefer declarative agent isolation (isolation: worktree) over ad hoc branch/worktree shell choreography where runtime supports it. 4. Keep manual git worktree fallback documented for non-Claude runtimes. 5. For long-running explorers/judges/workers, document background: true as the default custom-agent policy. 6. Use /effort to right-size model reasoning per agent role when spawning multi-agent workflows.

Review Cadence

• Re-verify this contract when:
• Claude Code changelog introduces new 2.1.x or 2.2.x entries
• any skill adds or changes multi-agent orchestration
• hook event support changes

<!-- TOC: Problem | THE EXACT PROMPT | Documentation First | Quick Start | The Layers | Agent-Assisted | Critical Searches | Output Template | Anti-Patterns | Checklist | References -->

Codebase Archaeology

Core Insight: Don't read randomly. Documentation first, then follow data flow from entry points outward.

The Problem

You land in an unfamiliar codebase. Where do you start? Random file reading wastes context. You need a systematic approach that builds understanding efficiently and produces a reusable "mental model" of the architecture.

---

THE EXACT PROMPT

For Deep Investigation (Spawning Explore Agent)

Thoroughly explore this codebase. I need to understand:

1. Overall architecture and module structure
2. How data flows through the system (input → processing → output)
3. Key data structures (the 3-5 types everything revolves around)
4. The integration points (external APIs, databases, file I/O)
5. Configuration system (env vars, config files, CLI flags)
6. Test infrastructure

Focus on src/ directory structure and main modules. Map out how the pieces fit together.
Be very thorough - I need a complete mental model of how this codebase works.

For Self-Directed Exploration

I want you to sort of randomly explore the code files in this project, choosing
code files to deeply investigate and trace their functionality through related
files. Build a comprehensive mental model of the architecture.

---

Documentation First (Critical!)

Before touching code, ALWAYS read:

cat AGENTS.md     # Project-specific rules and architecture notes
cat README.md     # Purpose, installation, usage

Why this matters:

• AGENTS.md often contains architecture diagrams, key decisions, gotchas
• README.md reveals the project's purpose and main workflows
• Skipping this wastes time rediscovering documented knowledge

---

Quick Start

# Phase 1: Orientation (2 min)
cat AGENTS.md README.md | head -200    # DOCUMENTATION FIRST!
ls -la src/ lib/ cmd/ pkg/             # Directory structure
cat Cargo.toml package.json pyproject.toml  # Dependencies

# Phase 2: Entry Points (5 min)
rg "fn main|async fn main" --type rust   # Rust entry
rg "clap|structopt|argparse|commander" . # CLI frameworks
rg "Router|routes|@app\." .              # HTTP routers

# Phase 3: Core Types (5 min)
rg "^(pub )?struct |^class |^interface " --type rust --type ts --type py
rg "impl .* for" --type rust             # Trait implementations

# Phase 4: Data Flow (10 min)
# Trace from entry → handler → service → storage

---

The Layers

┌─────────────────────────────────────┐
│ ENTRY POINTS (start here)           │
│ main(), CLI commands, HTTP routes   │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│ HANDLERS / CONTROLLERS              │
│ Request parsing, orchestration      │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│ CORE DOMAIN                         │
│ Business logic, key types           │
└─────────────┬───────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│ STORAGE / INTEGRATION               │
│ Database, files, external APIs      │
└─────────────────────────────────────┘

---

Agent-Assisted Exploration

For large codebases, spawn an Explore agent:

spawn_agent(agent_type="explorer")
Prompt: "Analyze the [project] codebase to provide a deep technical understanding.
Focus on:
1. Architecture Overview — how components interact
2. Key Data Structures — core types and their relationships
3. Data Flow — trace from ingestion to storage to output
4. Integration Points — external dependencies, APIs, databases"

Why agents help:

• They can read many files without filling your context
• They return a synthesized summary, not raw data
• You get architecture insights without the noise

---

Language-Specific Entry Points

---

Critical Searches

# Find entry points
rg "fn main|def main|function main|export default" .

# Find configuration
rg "env\.|process\.env|os\.environ|std::env" .
rg "config|settings|options" --type-add 'cfg:*.{toml,yaml,json}' -t cfg

# Find key types (the 3-5 everything revolves around)
rg "^(pub )?(struct|class|interface|type) \w+" --type rust --type ts --type py

# Find external integrations
rg "fetch\(|reqwest|aiohttp|requests\." .          # HTTP clients
rg "query|execute|SELECT|INSERT" .                  # Database
rg "open\(|File::|fs\." .                           # File I/O

# Find error handling (reveals edge cases)
rg "Error|Exception|panic|unwrap|expect" .

---

Output Template

After exploration, produce a Comprehensive Technical Summary:

## [Project Name] - Technical Architecture Summary

### Executive Summary
**[Project]** is a [type] that [purpose]. It implements [key patterns].

**Key Statistics:**
- ~X lines of code across Y modules
- Language: [lang] [version]
- Key dependencies: [list]

---

### Entry Points
- `src/main.rs:15` — CLI entry, parses args via clap
- `src/routes/mod.rs:1` — HTTP router (axum)

### Key Types
| Type | Location | Purpose |
|------|----------|---------|
| `Project` | src/model.rs:10 | Core domain object |
| `Config` | src/config.rs:5 | Runtime configuration |
| `Storage` | src/storage.rs:1 | Persistence layer |

### Data Flow

CLI args → Config::load() → Project::process() → Storage::save()

### External Dependencies
- SQLite via rusqlite (persistence)
- reqwest (HTTP client)
- tokio (async runtime)

### Configuration
| Source | Example |
|--------|---------|
| Env var | `CONFIG_PATH=/etc/tool.toml` |
| Config file | `~/.config/tool/config.toml` |
| CLI flag | `--verbose` |

---

Anti-Patterns

---

When to Use What

---

Checklist

• [ ] Read AGENTS.md/README.md — Documentation first!
• [ ] Orientation: Directory structure, dependencies
• [ ] Entry points: main(), CLI commands, HTTP routes
• [ ] Key types: The 3-5 structs/classes everything uses
• [ ] Data flow: Entry → processing → storage
• [ ] Config: Env vars, config files, defaults
• [ ] Integration: External APIs, databases, file I/O
• [ ] Tests: What do tests reveal about intended behavior?
• [ ] Produce summary: Create reusable architecture doc

---

References

Context Discovery Tiers

Purpose: Systematic approach to finding code/context before implementing.

Rule: Work top-to-bottom. Skip tiers if source unavailable.

---

Tier Order

---

Tier Details

Tier 1: Code-Map (Fastest)

Read docs/code-map/README.md   # Find category
Read docs/code-map/{feature}.md  # Get signposts

Why first: Local, instant, gives exact paths and function names.

Tier 2: Semantic Search

mcp__smart-connections-work__lookup --query="$TOPIC" --limit=10

Why second: Finds conceptual matches code-map might miss. Requires MCP.

Tier 3: Scoped Search

Grep("pattern", path="services/auth/")   # SCOPED
Glob("services/etl/**/*.py")             # SCOPED

Never: Grep("pattern") or Glob("**/*.py") on large repos.

Tier 4: Source Code

Read files identified by Tiers 1-3. Use function/class names, not line numbers.

Tier 5: Prior Knowledge

ls .agents/research/ | grep -i "$TOPIC"

Caution: May be stale. Always verify findings against current source.

Tier 6: External

• Context7: Library documentation
• WebSearch: External APIs, standards

---

Quick Reference

Code-Map → Semantic → Grep/Glob → Source → .agents/ → External
   ↓           ↓          ↓          ↓         ↓          ↓
 paths      meaning    keywords    code     history    docs

---

Tier Weights (Flywheel-Optimized)

Default weights based on typical value. Adjust based on GET /memories/analytics/sources:

Optimization loop:

# Query source analytics
curl -H "X-API-Key: $KEY" "$ETL_URL/memories/analytics/sources?collection=default"

# Response includes per-source value_score metrics:
# {
#   "sources": [
#     {"source_type": "smart-connections", "value_score": 0.72},
#     {"source_type": "grep", "value_score": 0.61},
#     ...
#   ],
#   "recommendations": [...]
# }

# Adjust weights based on value_score:
# value_score = (total_citations / memory_count) × avg_confidence × recency_factor
#
# - value_score > 0.5: Move source up in priority (increase weight)
# - value_score 0.3-0.5: Maintain current position
# - value_score < 0.3: Consider deprioritizing
# - value_score < 0.1 with high count: Review quality - many memories but rarely cited

Tool to source_type mapping (for session analyzer):

WebSearch → "web-search"
WebFetch → "web-fetch"
mcp__smart-connections-work__lookup → "smart-connections"
mcp__smart-connections-personal__lookup → "smart-connections"
mcp__ai-platform__search_knowledge → "compile-knowledge"
mcp__ai-platform__memory_recall → "memory-recall"
Grep → "grep"
Glob → "glob"
Read → "read"
LSP → "lsp"

---

Failure Pattern Prevention

Each tier helps prevent specific failure patterns from the Vibe-Coding methodology:

The 40% Context Rule

Critical: Never exceed 40% context utilization during discovery.

Why: Above 40%, Pattern #3 (Context Amnesia) kicks in. Quality degrades exponentially.

Defensive Epistemology

For each tier exploration, apply explicit reasoning:

DOING: [search/read action]
EXPECT: [what I expect to find]
IF WRONG: [what I'll conclude]

After:

RESULT: [what happened]
MATCHES: [yes/no]
THEREFORE: [conclusion]

This prevents Pattern #2 (Confident Hallucination) by forcing verification.

---

Anti-Patterns

Data Flow From Entry Points

Trace requests, jobs, and commands from the surface they enter on through every handler, dependency, and external sink they touch. Linear paths beat speculative breadth-first reads.

Why Trace From Entry Points

Most architectural questions reduce to "what happens when X arrives?" — an HTTP request, a CLI invocation, a queue message, a scheduled tick. Tracing one of these end-to-end produces:

• An accurate list of files actually involved (vs. files merely related by name).
• The real layering — handler vs. service vs. storage — instead of the layering the docs claim.
• The contract boundaries: what the handler validates, what the service trusts, where errors are caught vs. propagated.
• A reusable diagram other agents can verify by re-running the same trace.

---

The Four Entry Surfaces

A codebase usually has 1–3 of these. Find them all before tracing — you may need to trace one of each surface to understand the full shape.

---

Trace Procedure

For one chosen entry point:

Step 1: Locate the dispatcher

Find the registration call (router.add(...), app.command(...), consumer.subscribe(...)). Record the file:line and the handler symbol it routes to.

Step 2: Read the handler

Open the handler. Note, in order:

• Inputs and how they are validated.
• Direct dependencies the handler instantiates or receives (DI parameters, module-level singletons).
• External calls (DB, HTTP, filesystem, queue publish) made directly inside the handler.
• Errors caught vs. propagated.

Step 3: Walk the dependency tree one level deep

For each direct dependency, decide:

• Self-describing name? (UserRepository, EmailClient) — note its purpose without reading.
• Ambiguous name? Open it just long enough to write a one-line description.
• Touches an external sink? Always open it — the sink is part of the trace.

Stop at the second level unless a third level is obviously the place where the work actually happens.

Step 4: Find the sinks

Every trace ends at a sink. Common sinks:

Write the sink down. It is the trace's terminal node.

Step 5: Note error and retry behavior

Where in the trace are errors caught? Where do they propagate? Are retries or circuit breakers visible? This is where surprise behavior lives.

---

Output Shape

A trace artifact is short and linear:

## Trace: POST /api/jobs

Entry: `src/api/jobs.rs:42` → `create_job` handler

create_job (src/api/jobs.rs:42)
  ↓ validates JobRequest (src/api/jobs.rs:55)
  ↓ JobService::submit (src/services/job.rs:18)
       ↓ calls JobRepository::insert (src/storage/jobs.rs:30) — sink: SQLite
       ↓ calls Queue::publish (src/queue/mod.rs:22) — sink: Redis stream
  ↓ returns 202 with job id

Errors:
- Validation failure → 400 at handler boundary
- Storage failure → bubbles, logged in middleware (src/middleware/log.rs:12), returns 500
- Queue failure → swallowed at JobService::submit:24 — KNOWN GAP, see issue #...

One trace, one page. Multiple traces produce multiple short artifacts rather than one sprawling document.

---

Searches That Help

Use these scoped searches as starting points. Always pass a directory; never grep the whole repo unscoped.

# Entry-point registration
rg -n "Router::|router\.|@app\.|app\.(get|post)|Cmd\(\"|@click\.command|cobra\.Command" src/

# Handler signatures
rg -n "fn (handle|create|update|get|list|delete)_" src/api/ src/handlers/

# DB sinks
rg -n "query!?\(|execute!?\(|\.query\(|\.exec\(|SELECT |INSERT |UPDATE " src/

# HTTP egress
rg -n "reqwest::|requests\.|fetch\(|http\.Client" src/

# Queue publish
rg -n "publish\(|produce\(|enqueue\(|send_message" src/

Pair these with the iterative-retrieval pattern (skills/research/references/iterative-retrieval.md) when the first scoped search misses.

---

Anti-Patterns

---

When to Use This Reference

• You are answering "what happens when <event> arrives?"
• You need a short artifact that another agent can verify or extend.
• You are about to modify a handler and need to understand its blast radius.
• The architecture docs disagree with the code, and you need the ground-truth path.

For broad onboarding, pair this with skills/research/references/onboarding-methodology.md. For prior-work search, see skills/research/references/iterative-retrieval.md.

---

Pattern adopted from codebase-archaeology (ACFS skill corpus). Methodology only — no verbatim text.

Deep Research with MCP Integration

Multi-source research using MCP servers (firecrawl, exa, context7) for comprehensive exploration beyond basic web search.

When to Use

• Topic requires authoritative external sources (not just codebase exploration)
• Research question spans multiple domains or requires current data
• Basic WebSearch returns insufficient depth
• API documentation or technical specifications needed

Research Pipeline

Step 1: Decompose Topic into Sub-Questions

Break the research topic into 3-5 focused sub-questions:

Topic: "Impact of streaming APIs on agent architectures"
Sub-questions:
  1. What streaming API patterns exist today? (SSE, WebSocket, gRPC streams)
  2. How do major agent frameworks handle streaming? (LangChain, CrewAI, AutoGen)
  3. What are latency/throughput tradeoffs for streaming vs batch?
  4. What production deployment patterns exist for streaming agents?
  5. What's the state of streaming in Claude/OpenAI APIs?

Step 2: Multi-Source Search (Per Sub-Question)

For each sub-question, search across available MCP sources:

# Primary: Structured web search (if firecrawl MCP connected)
mcp__firecrawl__search(query: "<sub-question keywords>", limit: 8)

# Secondary: Semantic web search (if exa MCP connected)
mcp__exa__web_search(query: "<sub-question keywords>", numResults: 8)
mcp__exa__web_search_advanced(query: "<keywords>", numResults: 5, startPublishedDate: "2025-01-01")

# Tertiary: Documentation lookup (if context7 MCP connected)
mcp__context7__resolve_library_id(libraryName: "<library>")
mcp__context7__get_library_docs(context7CompatibleLibraryID: "<id>")

# Fallback: Standard web search (always available)
WebSearch(query: "<sub-question>")

Search Strategy:

• Use 2-3 keyword variations per sub-question
• Mix general queries with news-focused queries
• Aim for 15-30 unique sources total across all sub-questions
• Prioritize: official docs > academic > reputable news > blogs > forums

Step 3: Deep-Read Key Sources (3-5 URLs)

For the most promising results, fetch full content:

# Full page scrape (if firecrawl connected)
mcp__firecrawl__scrape(url: "<url>")

# Semantic content extraction (if exa connected)
mcp__exa__crawling(url: "<url>", tokensNum: 5000)

# Fallback
WebFetch(url: "<url>")

Step 4: Parallel Agent Research (Optional)

For broad topics, spawn parallel research agents:

Agent 1: Sub-questions 1-2 (technical patterns)
Agent 2: Sub-questions 3-4 (production deployment)
Agent 3: Sub-question 5 (API state-of-art)

Main session synthesizes all agent findings into unified report.

Step 5: Synthesize Report

# Research: <Topic>

**Sources:** <N> | **Confidence:** High/Medium/Low | **Date:** <YYYY-MM-DD>

## Executive Summary
<3-5 sentences>

## 1. <Theme from Sub-Question 1>
<Findings with inline citations>
- Key point (Source Name, with URL citation)

## Key Takeaways
- <Actionable insight 1>
- <Actionable insight 2>

## Knowledge Gaps
- <What we couldn't find>
- <What needs verification>

## Sources
1. Source Title — one-line summary (with URL)

Quality Rules

1. Every claim needs a source — no unsourced assertions 2. Cross-reference: If only one source says it, flag as unverified 3. Prefer recent sources (last 12 months) for fast-moving topics 4. Acknowledge gaps explicitly — "insufficient data found" > hallucination 5. Separate fact from inference — label estimates, projections, opinions 6. Check MCP availability first — gracefully degrade to WebSearch if MCPs not connected

MCP Detection

Before attempting MCP-based search, check availability:

# Check which MCPs are available in the current session
# If firecrawl: use firecrawl_search + firecrawl_scrape
# If exa: use web_search_exa + crawling_exa
# If context7: use for library documentation
# If none: fall back to WebSearch + WebFetch

Log which sources were used for traceability in the report's Methodology section.

Integration with /research Skill

This reference extends the research skill's Step 3 (Launch Explore Agent) with MCP-first search patterns. When the explore agent's Tier 6 (External Docs) triggers, use this pipeline instead of basic WebSearch.

The iterative retrieval pattern (references/iterative-retrieval.md) applies here too: score MCP results for relevance, extract new search terms, and refine across cycles.

Research Document Template

Filename Format

.agents/research/YYYY-MM-DD-{topic-slug}.md

Convert topic to kebab-case slug:

• "authentication flow" -> 2026-01-03-authentication-flow.md
• "MCP server architecture" -> 2026-01-03-mcp-server-architecture.md

---

Required Sections

1. Frontmatter

---
date: YYYY-MM-DD
type: Research
topic: "Topic Name"
tags: [research, domain, tech]
status: COMPLETE
supersedes: []
---

2. Executive Summary

2-3 sentences: what found, what recommend.

3. Current State

• What exists today
• Key files table: | File | Purpose |
• Existing patterns

4. Findings

Each finding with:

• Evidence: file:line
• Implications

5. Constraints

6. Risks

7. Recommendation

• Recommended approach
• Rationale
• Alternatives considered and rejected

8. Discovery Provenance

Track which sources provided key insights (enables flywheel optimization).

Purpose: Create an audit trail showing which discovery method found each insight. This enables post-hoc analysis: "Which sources led to successful implementation?"

When to complete: As you research, add one row per significant finding showing its source.

Example:

| Finding | Source Type | Source Detail | Confidence |
|---------|-------------|---------------|------------|
| Gateway request flow | code-map | docs/code-map/gateway.md | 1.0 |
| Middleware pattern | smart-connections | "request middleware chain" | 0.95 |
| Error handling at L45 | grep | services/gateway/middleware.py | 1.0 |
| Rate limiting precedent | prior-research | 2026-01-10-ratelimit.md | 0.85 |
| OAuth2 RFC | web-search | "RFC 6749 OAuth 2.0" | 0.80 |

Source Types by Tier (higher tier = better quality):

Tier 1 (Authoritative)

• code-map - Structured architecture documentation (highest confidence)

Tier 2 (Semantic)

• smart-connections - Obsidian semantic search
• compile-knowledge - MCP ai-platform search

Tier 3 (Scoped Search)

• grep - Pattern matching in code
• glob - File pattern matching

Tier 4 (Source Code)

• read - Direct file reading
• lsp - Language Server Protocol queries

Tier 5 (Prior Art)

• prior-research - Previous research documents
• prior-retro - Retrospective learnings
• prior-pattern - Reusable patterns
• memory-recall - Semantic memory search

Tier 6 (External)

• web-search - Web search results
• web-fetch - Direct URL fetch

Other

• conversation - User-provided context

Confidence scoring:

• 1.0 - Source is authoritative/written down
• 0.95 - Semantic match, high relevance
• 0.85 - Good match, may need verification
• 0.70 - Reasonable match, verify
• < 0.70 - Use sparingly, needs verification

9. Failure Pattern Risks

Identify which of the 12 failure patterns are risks for this work. This proactive assessment helps downstream implementation avoid known pitfalls.

Required table:

## Failure Pattern Risks

| Pattern | Risk Level | Mitigation |
|---------|------------|------------|
| #N Pattern Name | HIGH/MEDIUM/LOW | Specific mitigation strategy |

Pattern quick reference:

Example:

## Failure Pattern Risks

| Pattern | Risk Level | Mitigation |
|---------|------------|------------|
| #2 Confident Hallucination | HIGH | External OAuth API - verify all claims against official docs |
| #5 Eldritch Horror | MEDIUM | Auth middleware is 400+ lines - document boundaries before changes |
| #9 Cargo Cult | MEDIUM | Using external OAuth example - understand why each step exists |
| #11 Security Theater | HIGH | Auth changes - use established patterns, get security review |

10. Next Steps

Point to /plan for implementation.

---

Tag Vocabulary

Rules: 3-5 tags total. First tag MUST be research.

Examples:

• [research, agents, mcp] - MCP server research
• [research, data, neo4j] - Data storage research
• [research, security, auth] - Authentication research

---

Status Values

The 12 Failure Patterns (Research Reference)

Based on the Vibe-Coding methodology. Load this when you need full pattern details for risk assessment.

---

Quick Reference

---

Inner Loop Patterns (Seconds-Minutes)

1. The Fix Spiral

Description: Making a fix that breaks something else, then fixing that break which causes another issue, creating a cascading chain without resolution.

Symptoms:

• More than 3 fix attempts without convergence
• Changes oscillating between two states
• "This should work" appearing in explanations
• Error messages changing but not disappearing

Research Defense:

• Research root cause BEFORE attempting fix
• Document expected behavior vs actual behavior
• Identify all code paths affected

Prevention:

• Set hard limit: 3 attempts then STOP
• State explicit prediction before each fix
• Checkpoint working state before each attempt

---

2. The Confident Hallucination

Description: Generating plausible-sounding but factually incorrect information about APIs, libraries, or behavior.

Symptoms:

• Code references non-existent methods or parameters
• API usage that "looks right" but fails at runtime
• Overly specific technical claims without evidence
• Version-specific features applied to wrong versions

Research Defense:

• VERIFY all API claims against actual documentation
• Note confidence levels in provenance table
• Use Tier 6 (external docs) for unfamiliar APIs

Prevention:

• Test code in isolation before integration
• Use "I don't know" as valid response
• Run type checkers and linters early

---

3. The Context Amnesia

Description: As context window fills, losing track of earlier constraints, requirements, or decisions.

Symptoms:

• Reintroducing previously fixed bugs
• Contradicting earlier decisions
• Forgetting project-specific conventions
• Repeating completed work

Research Defense:

• Stay <40% context utilization
• Write findings to files immediately
• Use targeted reads (offset/limit) not full files

Prevention:

• Save progress frequently
• Start fresh sessions for distinct work
• Front-load critical constraints

---

4. The Tests Passing Lie

Description: Tests pass but code doesn't actually work - too narrow, wrong thing, mocks away behavior.

Symptoms:

• Green test suite but broken functionality
• Tests that test mocks instead of real behavior
• Coverage looks good but edge cases fail
• Tests modified in same PR as code they test

Research Defense:

• Find actual test coverage in research
• Identify what tests actually verify
• Note mocked vs real dependencies

Prevention:

• Run tests yourself; don't trust reported results
• Separate test changes from code changes
• Manual smoke test after suite passes

---

Middle Loop Patterns (Hours-Days)

5. The Eldritch Horror

Description: Code becomes incomprehensible - functions spanning hundreds of lines, deeply nested logic, unclear naming.

Symptoms:

• Functions exceeding 200 lines
• Nesting depth beyond 4 levels
• Variable names like temp2, data3
• Comments that don't match behavior

Research Defense:

• Document complexity limits in findings
• Note current complexity metrics
• Identify refactoring boundaries

Prevention:

• Enforce hard limits: <200 lines per function
• Require meaningful names
• Use explicit interfaces

---

6. The Silent Deletion

Description: Removing code that appears unused but is actually necessary for edge cases, legacy support, or fallbacks.

Symptoms:

• "Cleanup" commits that remove "dead code"
• Features that worked yesterday now fail
• Error handling mysteriously missing
• Comments about "why" deleted along with code

Research Defense:

• Research WHY code exists before removal
• Check git history for context
• Trace all references including dynamic calls

Prevention:

• Never delete without understanding purpose
• Get human approval for deletion
• Keep deleted code in comments initially

---

7. The Zombie Resurrection

Description: Previously fixed bugs return because similar code regenerated without fix, or reverts during refactoring.

Symptoms:

• Bug reports for issues marked "fixed"
• Same error in different code paths
• Fixes lost during refactoring
• "I thought we fixed this" conversations

Research Defense:

• Prior art search prevents re-solving
• Check for existing regression tests
• Document root cause, not just fix

Prevention:

• Add regression tests for every fix
• Use automated checks for anti-patterns
• Keep lessons learned file

---

8. The Gold Plating

Description: Adding unrequested features, extra error handling, additional configurability beyond what was asked.

Symptoms:

• PR larger than expected
• New config options no one asked for
• "While I was here, I also..." explanations
• Abstraction layers for single use cases

Research Defense:

• Define explicit scope in research
• Note ONLY what's needed for the task
• Separate "nice to have" from "required"

Prevention:

• Define explicit scope before starting
• Reject changes outside stated scope
• Prefer boring, obvious solutions

---

Outer Loop Patterns (Days-Weeks)

9. The Cargo Cult

Description: Copying patterns from examples without understanding why they work. May be inappropriate for context.

Symptoms:

• Copy-pasted code with irrelevant portions
• Patterns from different frameworks mixed
• "Best practices" where they don't fit
• Configuration copied without understanding

Research Defense:

• Understand WHY patterns exist
• Ask "why does this pattern exist?" for each
• Verify example matches your context

Prevention:

• Test copied code in isolation first
• Adapt patterns to local conventions
• Trace examples to their source

---

10. The Premature Abstraction

Description: Creating generic abstractions before concrete use cases exist. Abstractions don't match actual needs.

Symptoms:

• Generic interfaces with one implementation
• Factory patterns for single classes
• Configuration for cases that don't exist
• "Future-proofing" never used

Research Defense:

• Document concrete use cases first
• Require 3+ concrete cases before abstracting
• Note where duplication exists vs speculation

Prevention:

• Write concrete implementations first
• Prefer duplication over wrong abstraction
• Extract only when duplication appears

---

11. The Security Theater

Description: Code appears secure but isn't - validation that misses edge cases, encryption with hardcoded keys.

Symptoms:

• Security measures easily circumvented
• Validation on client but not server
• Hardcoded credentials or keys
• "Security by obscurity" approaches

Research Defense:

• Include security constraints in research
• Reference external security standards
• Note auth/crypto/access control patterns

Prevention:

• Use established security libraries
• Security review by qualified humans
• Static analysis for vulnerabilities

---

12. The Documentation Mirage

Description: Documentation exists but doesn't match reality - outdated READMEs, incorrect API docs.

Symptoms:

• Following docs leads to errors
• Comments contradict adjacent code
• Examples that don't compile
• Setup instructions that don't work

Research Defense:

• Verify docs match reality
• Test documentation by following it literally
• Note discrepancies in research findings

Prevention:

• Treat docs as code: test them
• Update docs in same PR as code
• Use executable documentation

---

Pattern Frequency Tracking

Use this in research outputs to track which patterns are relevant:

## Failure Pattern Risks

| Pattern | Risk Level | Mitigation |
|---------|------------|------------|
| #2 Confident Hallucination | HIGH | Verify external API claims |
| #5 Eldritch Horror | MEDIUM | Keep functions <200 lines |
| #9 Cargo Cult | MEDIUM | Understand why patterns exist |

Risk Levels:

• HIGH: Strong indicators in research, requires explicit mitigation
• MEDIUM: Some indicators, requires awareness
• LOW: Minor indicators, standard practices sufficient

---

See Also

• ~/.claude/CLAUDE-base.md - Core Vibe-Coding methodology
• ~/.claude/plugins/marketplaces/agentops-marketplace/reference/failure-patterns.md - Full pattern reference
• ~/.claude/skills/crank/failure-taxonomy.md - Execution failure taxonomy

Iterative Retrieval Pattern

Progressive context refinement for subagents. Solves "I don't know what I need to know."

Problem

When spawning research or explore agents, the initial query often misses critical context because:

• The agent doesn't know the codebase's naming conventions
• Related features use unexpected terminology
• Key context lives in files the agent wouldn't think to search

Flat keyword search returns either too much noise or misses relevant files.

Solution: 4-Phase Iterative Loop

Phase 1: DISPATCH — Broad keyword search

Search for: <topic>
Use 3-5 keyword variants:
  - Exact term: "<topic>"
  - Synonyms: "<synonym1>", "<synonym2>"
  - Implementation terms: "<likely-function-name>", "<likely-file-pattern>"

Phase 2: EVALUATE — Score relevance (0-1)

For each result, assign a relevance score:

Phase 3: REFINE — Extract new keywords

From high-relevance files (0.5+), extract:

• Function/class names referenced but not yet searched
• Import paths pointing to unexplored modules
• Config keys or env vars mentioned
• Error messages or log strings (grep targets)

Add these as new search terms.

Phase 4: LOOP — Repeat max 3 cycles

Cycle 1: Broad search → find core files → extract new terms
Cycle 2: Targeted search with extracted terms → find related files → more terms
Cycle 3: Fill remaining gaps → verify completeness

Stop early if:

• No new high-relevance results in a cycle
• All critical questions answered
• Context budget reached

Integration with /research

In Step 3 (Launch Explore Agent), add iterative retrieval to the exploration prompt:

Use iterative retrieval:
1. Start with broad keyword search for "<topic>"
2. Score each result 0-1 for relevance
3. From files scoring 0.5+, extract new search terms
4. Search with new terms (max 3 cycles)
5. Report: files found per cycle, relevance scores, final coverage

Integration with /swarm

When spawning parallel workers that need codebase context:

Before implementation, run 1-2 retrieval cycles to gather context:
- Search for files related to your task
- Read the highest-relevance files (0.7+)
- Note patterns and conventions from those files
- Then implement following those patterns

This prevents workers from reinventing patterns that already exist in the codebase.

Example: Researching "authentication"

Cycle 1:

• Search: "auth", "authentication", "login", "session"
• Hits: auth/middleware.go (0.9), auth/token.go (0.8), config/auth.go (0.6), README.md (0.2)
• New terms from hits: ValidateToken, SessionStore, JWT_SECRET

Cycle 2:

• Search: "ValidateToken", "SessionStore", "JWT_SECRET"
• Hits: store/session.go (0.9), config/env.go (0.7), test/auth_test.go (0.8)
• New terms: RefreshToken, store.NewRedisStore

Cycle 3:

• Search: "RefreshToken", "RedisStore"
• Hits: auth/refresh.go (0.9), store/redis.go (0.8)
• No new high-relevance terms → STOP

Result: Complete auth system map in 3 cycles vs flat search that would miss store/ and config/env.go.

Anti-Patterns

Onboarding Methodology

Build a working mental model of an unfamiliar codebase fast. Read the docs first, locate entry points, then trace one representative path to its sink — never random file reads.

Problem

Landing in a new codebase, the temptation is to grep for keywords or open files at random. That burns context without producing structure. Onboarding research needs a repeatable shape: orient on docs, locate entry points, identify the 3–5 types everything revolves around, then trace one representative flow end-to-end. The output should be reusable: another agent (or future you) reads the summary and skips the cold-start cost.

---

Phased Walk

If a phase has no signal in 90 seconds, skip and note the gap.

---

Phase 1: Documentation First

Read in this order before opening source:

cat AGENTS.md     # Project rules, architecture decisions, gotchas
cat CLAUDE.md     # Same — most repos symlink one to the other
cat README.md     # Stated purpose, install, primary workflows
ls docs/ && cat docs/index.md docs/architecture.md 2>/dev/null

Capture three things from this pass: 1. The project's stated purpose in one sentence. 2. The top 3 conventions or rules the docs call out. 3. Any explicit "do not touch" or "load-bearing" warnings.

Skipping this phase is the most common onboarding failure — it makes you rediscover documented constraints by trial and error.

---

Phase 2: Inventory the Surface

ls -la                          # Top-level shape
ls -la src/ lib/ cmd/ pkg/      # Source roots
cat Cargo.toml package.json pyproject.toml go.mod 2>/dev/null

Annotate each top-level directory with a one-line guess at its role. Confirm the guesses in later phases.

---

Phase 3: Entry Points

Use language-aware searches — see skills/research/references/context-discovery.md for tier ordering. Patterns to look for:

Record each as file:line — these become navigation anchors in the summary.

---

Phase 4: Core Types

Look for the 3–5 types everything else flows through. Signals:

• Mentioned in most files when grepped by name.
• Returned or consumed by multiple entry-point handlers.
• Declared in a model.rs, types.ts, schema.py, or equivalent root.

Capture each in a table: name, location, purpose, key fields. If you cannot describe the purpose in one sentence, the type is not yet understood — flag it as a gap.

---

Phase 5: Trace One Flow

Pick the most representative entry-point handler. Walk it:

1. Read the handler. Note every function it calls. 2. For each callee, decide: do I need to open it, or is the name self-describing? 3. Stop when you hit storage, an external API, or a return that closes the loop. 4. Write the path as a linear arrow chain.

One traced flow is more useful than five half-traced flows.

---

Phase 6 & 7: Integrations and Tests

Integrations: list the DBs, HTTP clients, file paths, and queues touched by the traced flow. Note the library used for each.

Tests: read 1–2 test files for the traced flow. The asserts reveal which behaviors the team treats as invariants.

---

Mental-Model Output Template

Write the summary as .agents/research/YYYY-MM-DD-<project>-mental-model.md using this shape. Keep it under one page.

---
date: YYYY-MM-DD
type: Research
topic: "<project> onboarding mental model"
tags: [research, onboarding, architecture]
status: COMPLETE
---

# <Project> — Mental Model

## Executive Summary
<2–3 sentences: what it is, what it does, the one architectural choice that defines it.>

## Entry Points
| Surface | Location | Purpose |
|---------|----------|---------|
| CLI | `src/main.rs:15` | clap parser, dispatches to subcommand |
| HTTP | `src/routes/mod.rs:1` | axum router, mounts `/api/*` |

## Key Types
| Type | Location | Purpose |
|------|----------|---------|
| `Project` | `src/model.rs:10` | Core domain object |
| `Config` | `src/config.rs:5` | Runtime configuration loaded once |
| `Storage` | `src/storage.rs:1` | Persistence boundary |

## Data Flow (representative path)
CLI args → `Config::load()` → `Project::process()` → `Storage::save()`

## External Dependencies
| System | Library | Where touched |
|--------|---------|---------------|
| SQLite | rusqlite | `src/storage.rs` |
| HTTP   | reqwest  | `src/clients/api.rs` |

## Configuration Surfaces
| Source | Example |
|--------|---------|
| Env var | `CONFIG_PATH=/etc/tool.toml` |
| File | `~/.config/tool/config.toml` |
| Flag | `--verbose` |

## Testing Surface
- `tests/integration_test.rs` covers the CLI → storage path end-to-end.
- Property tests in `tests/prop/` assert <invariant>.
- Gaps: <untested surfaces noted during the read>.

## Gaps and Open Questions
- <Files skipped because purpose unclear>
- <Areas where docs disagree with code>

---

Anti-Patterns

---

Checklist

• [ ] AGENTS.md and README.md read before any source file.
• [ ] Top-level directory annotated.
• [ ] Entry points listed with file:line.
• [ ] 3–5 core types named with one-sentence purposes.
• [ ] One representative flow traced end-to-end.
• [ ] Integrations and tests noted.
• [ ] Summary written under .agents/research/ using the template.
• [ ] Gaps explicitly listed — no false completeness.

---

Pattern adopted from codebase-archaeology (ACFS skill corpus). Methodology only — no verbatim text.

Ralph Loop Contract (Reverse-Engineered)

This contract captures the operational Ralph mechanics reverse-engineered from:

• https://github.com/ghuntley/how-to-ralph-wiggum
• .tmp/how-to-ralph-wiggum/README.md
• .tmp/how-to-ralph-wiggum/files/loop.sh
• .tmp/how-to-ralph-wiggum/files/PROMPT_plan.md
• .tmp/how-to-ralph-wiggum/files/PROMPT_build.md

Use this as the source-of-truth for Ralph alignment in AgentOps orchestration skills.

Core Contract

1. Fresh context every iteration/wave.

• Each execution unit starts clean; no carryover worker memory.

2. Scheduler-heavy, worker-light.

• The lead/orchestrator schedules and reconciles.
• Workers perform one scoped unit of work.

3. Disk-backed shared state.

• Loop continuity comes from filesystem state, not accumulated chat context.
• In classic Ralph: IMPLEMENTATION_PLAN.md and AGENTS.md.

4. One-task atomicity.

• Select one important task, execute, validate, persist state, then restart fresh.

5. Backpressure before completion.

• Build/tests/lint/gates must reject bad output before task completion/commit.

6. Observe and tune outside the loop.

• Humans (or lead agents) monitor outcomes and adjust prompts/constraints/contracts.

AgentOps Mapping

Implementation Notes

• Keep worker prompts concise and operational.
• Keep state in files/issue trackers, not long conversational memory.
• Prefer deterministic checks over subjective completion.

research-software — Software Research

Rules: Latest STABLE tag (not main). Filter to 2025-2026. Code > Docs. Skip Stack Overflow.

Output First

Every research produces this structure:

## [Tool] vX.Y.Z (YYYY-MM-DD)

**Repo:** github.com/org/repo @ abc123

### Commands
| Task | Command | Notes |
|------|---------|-------|

### Config
| Option | Default | Notes |
|--------|---------|-------|

### Env Vars
| Variable | Purpose |
|----------|---------|

### Gotchas
- [problem]: [fix]. Source: [PR/issue/code]

### Sources
- Code: [file:line]
- PRs: #123, #456
- Posts: [url]

---

THE PROMPT

Research [TOOL] for [PURPOSE].
Clone to /tmp, checkout latest stable tag.
Spawn Explore agent on source. Find: CLI, config, hidden flags, env vars.
Parallel: GitHub PRs/issues, web search "[tool] 2025".
Output: skill-ready markdown.

---

Pipeline

# 0. Detect context (if in a project)
# Check package.json, Cargo.toml, pyproject.toml for existing versions

# 1. Clone + stable tag
git clone --depth 1 https://github.com/[org]/[repo] /tmp/[repo]-research
cd /tmp/[repo]-research && git fetch --tags && git checkout $(git describe --tags --abbrev=0)

# 2. Spawn Explore agent (parallel with step 3-4)
# → "Find all CLI commands, config options, hidden flags, env vars in /tmp/[repo]-research"

# 3. GitHub activity
gh pr list -R [org]/[repo] --state merged --limit 30 --json title,mergedAt
gh issue list -R [org]/[repo] --label question --limit 20

# 4. Web search
# → "[tool] 2025" "[tool] 2026" "[tool] tutorial"

# 5. Synthesize → Output structure above

# 6. Cleanup
rm -rf /tmp/[repo]-research

---

Checklist

• [ ] Detect context: Check package.json/Cargo.toml/pyproject.toml for versions
• [ ] Clone repo to /tmp, checkout latest stable tag
• [ ] Explore agent: CLI commands, config schema, hidden flags, env vars
• [ ] GitHub: Recent merged PRs, issues tagged "question"/"documentation"
• [ ] Web search: "[tool] 2025", "[tool] 2026", skip pre-2025
• [ ] Synthesize: Commands table, config table, gotchas, patterns
• [ ] Cite sources: repo@commit, PR numbers, blog URLs
• [ ] Clean up: rm -rf /tmp/[repo]-research

---

Source Priority

1. Source code (actual behavior)
2. Recent PRs (features being added)
3. GitHub issues (real problems)
4. Blog posts 2025-2026 (practical patterns)
5. Official docs (baseline, often outdated)

Skip: Stack Overflow, anything pre-2025, basic tutorials

---

Top Mistakes

---

Key Searches

# Hidden/experimental flags
rg "hidden|experimental|unstable" /tmp/[repo]-research

# Environment variables by language
rg "process\.env\." /tmp/[repo]-research --type ts    # TypeScript
rg "std::env::" /tmp/[repo]-research --type rust      # Rust
rg "os\.environ" /tmp/[repo]-research --type py       # Python
rg "os\.Getenv" /tmp/[repo]-research --type go        # Go

# Recent changes
git log --oneline --since="2025-06-01" | head -30

---

Done When

• [ ] Have version number from stable tag
• [ ] Commands table has 5+ entries
• [ ] Config table covers main options
• [ ] Gotchas section has 3+ real issues from GitHub/code
• [ ] All sources cited with links

---

Decision Tree

What are you researching?
│
├─ CLI tool (wrangler, cargo, bun)
│  Focus: src/cli/, commands, flags, env vars
│
├─ Library/Framework (React, Next.js)
│  Focus: packages/*/src/, exported APIs, deprecations
│
├─ Runtime (Bun, Deno, Node)
│  Focus: built-ins, runtime flags, compat layers
│
└─ Database/Service (D1, R2, Postgres)
   Focus: query syntax, config, limits, gotchas

Key Searches by Type

Deep strategies: STRATEGIES.md

---

Subagent: Code Investigator

Investigate /tmp/[repo]-research for [TOOL].
Find: CLI commands, config options, hidden/experimental flags, env vars.
Check git log --oneline -30 for recent changes.
Output as markdown tables.

Use model: sonnet (balance of speed + depth)

---

Subagent: Web Researcher

Search "[TOOL] 2025" and "[TOOL] 2026".
Find 5-10 recent tutorials, blog posts, announcements.
Extract: patterns, gotchas, tips.
Skip: Stack Overflow, anything pre-2025, basic tutorials.

Use model: haiku (fast, web-focused)

---

References

Research Examples

Real sessions showing the workflow.

---

CLI Tool: Wrangler

# 1. Clone
git clone --depth 1 https://github.com/cloudflare/workers-sdk.git /tmp/workers-sdk-research
cd /tmp/workers-sdk-research && git fetch --tags && git checkout $(git describe --tags --abbrev=0)

# 2. Explore agent prompt:
# "Investigate /tmp/workers-sdk-research/packages/wrangler: CLI commands, config schema, hidden flags, env vars"

# 3. GitHub
gh pr list -R cloudflare/workers-sdk --state merged --limit 30 --json title,mergedAt
gh issue list -R cloudflare/workers-sdk --label "question" --limit 20

# 4. Web search: "wrangler 2025", "cloudflare workers tutorial 2026"

# 5. Cleanup
rm -rf /tmp/workers-sdk-research

Key findings location: packages/wrangler/src/ — commands in src/, config schema in types.

---

Framework: Next.js

# 1. Clone + stable tag
git clone --depth 1 https://github.com/vercel/next.js.git /tmp/nextjs-research
cd /tmp/nextjs-research && git fetch --tags && git checkout $(git describe --tags --abbrev=0)

# 2. Explore agent prompt:
# "Investigate /tmp/nextjs-research/packages/next/src: exported APIs, experimental flags, config options"

# 3. Quick searches
rg "experimental" /tmp/nextjs-research/packages/next/src/server/config-shared.ts
rg "deprecated" /tmp/nextjs-research/packages/next/src --type ts | head -20

# 4. Web search: "next.js 15 2025", "next.js app router 2026"

# 5. Cleanup
rm -rf /tmp/nextjs-research

Key findings location: packages/next/src/server/config-shared.ts for all config options.

---

Runtime: Bun

# 1. Clone
git clone --depth 1 https://github.com/oven-sh/bun.git /tmp/bun-research
cd /tmp/bun-research && git fetch --tags && git checkout $(git describe --tags --abbrev=0)

# 2. Explore agent prompt:
# "Investigate /tmp/bun-research/src: CLI flags, built-in APIs (Bun.*), env vars"

# 3. Quick searches
rg "process\.env\." /tmp/bun-research/src --type ts | head -30
rg "Bun\." /tmp/bun-research/packages/bun-types/bun.d.ts | head -50

# 4. Web search: "bun runtime 2025", "bun vs node 2026"

# 5. Cleanup
rm -rf /tmp/bun-research

Key findings location: packages/bun-types/ for all Bun.* APIs.

---

Typical Output

After Wrangler research:

## Wrangler v4.59.2 (2026-01-15)

**Repo:** github.com/cloudflare/workers-sdk @ abc123

### Commands
| Task | Command |
|------|---------|
| Dev | `wrangler dev` |
| Deploy | `wrangler deploy` |
| Tail logs | `wrangler tail` |
| Types | `wrangler types` |

### Config
| Option | Default | Notes |
|--------|---------|-------|
| `name` | required | Worker name |
| `main` | required | Entry point |
| `compatibility_date` | required | Runtime version |

### Gotchas
- **wrangler.toml vs wrangler.jsonc**: jsonc now recommended. Source: PR #1234
- **Auto-provisioning**: KV/R2/D1 auto-created if id omitted. Source: v4.50 release

### Sources
- Code: packages/wrangler/src/config/config.ts:45
- PRs: #5678, #5679
- Posts: blog.cloudflare.com/wrangler-4 (2025-09)

Output Templates

Expanded templates for specific tool types. Basic structure is in SKILL.md.

---

CLI Tool (Expanded)

## [Tool] vX.Y.Z (YYYY-MM-DD)

**Repo:** github.com/org/repo @ abc123

### Commands
| Task | Command | Notes |
|------|---------|-------|
| [task] | `[cmd]` | Added in vX.Y |

### Flags (Including Hidden)
| Flag | Description | Source |
|------|-------------|--------|
| `--flag` | [desc] | docs |
| `--hidden` | [desc] | source: file:123 |

### Config (`[filename]`)

[section] option = "default" # [description]

### Env Vars
| Variable | Default | Notes |
|----------|---------|-------|
| `VAR` | [default from code] | [notes] |

### Bleeding Edge (unreleased)
| Feature | PR | Status |
|---------|-----|--------|
| [feature] | #123 | merged, not released |

### Gotchas
- **[Issue]**: [fix]. Source: #456

### Patterns

// From: [tests/blog post] [code]

### Sources
- Repo: [url] @ [commit]
- PRs: #123, #456
- Posts: [url] (2025-MM)

---

Library/Framework

## [Library] vX.Y.Z (YYYY-MM-DD)

**Install:** `[package manager command]`

### Core API
| Export | Purpose | Since |
|--------|---------|-------|
| `name` | [purpose] | vX.Y |

### New in Latest Release
| API | Description |
|-----|-------------|
| `name` | [desc] |

### Config

{ option: "default", // [description] }

### Patterns (2025-2026)

// Source: [blog/tests] [code]

### Migration (from vX to vY)
- [breaking change]: [fix]

### Gotchas
- [issue]: [solution]

---

Comparison

When researching alternatives:

## [Tool A] vs [Tool B]

| Aspect | [A] | [B] |
|--------|-----|-----|
| Version | vX | vY |
| [aspect] | [A way] | [B way] |

### Use [A] when
- [scenario]

### Use [B] when
- [scenario]

### Migration A → B
1. [step]

---

Minimal (Quick Research)

## [Tool] (YYYY-MM-DD)

**Install:** `[cmd]`
**Key:** `[most common cmd]`
**Gotcha:** [one gotcha + fix]
**New:** [one 2025-2026 feature]
**Source:** [repo@commit]

Tool-Specific Research Strategies

Deep-dive strategies for different tool categories.

---

CLI Tools (wrangler, cargo, bun, etc.)

Where to Look

src/cli/ or src/cli.rs or bin/
├── Command definitions
├── Argument parsing (clap, yargs, etc.)
├── Hidden/experimental flags
└── Default values (often different from docs)

Key Searches

# Rust CLI
rg "hidden\s*=\s*true" /tmp/[repo]-research --type rust
rg "#\[arg\(" /tmp/[repo]-research --type rust

# TypeScript CLI
rg "hidden:|experimental:" /tmp/[repo]-research --type ts
rg "process\.env\." /tmp/[repo]-research --type ts

# Go CLI
rg "Hidden:\s*true" /tmp/[repo]-research --type go
rg "os\.Getenv" /tmp/[repo]-research --type go

Output Focus

• Commands table with all subcommands
• Flags table (including hidden)
• Environment variables
• Config file schema
• Common patterns

---

Libraries/Frameworks (React, Next.js, etc.)

Where to Look

packages/[core]/src/
├── Exported APIs (index.ts, exports.ts)
├── Internal APIs (not exported)
├── Deprecation warnings
└── Experimental/canary exports

Key Searches

# Find exports
rg "^export " /tmp/[repo]-research/packages/*/src/index.ts

# Find deprecations
rg "deprecated|@deprecated" /tmp/[repo]-research

# Find experimental
rg "experimental|unstable|canary" /tmp/[repo]-research

Output Focus

• API reference table
• New APIs (latest release)
• Deprecated APIs (with migration)
• Config options
• Patterns from examples/

---

Runtimes (Bun, Deno, Node)

Where to Look

src/
├── Built-in modules
├── Runtime flags
├── Environment variables
├── Compatibility layers
└── Performance options

Key Searches

# Runtime flags
rg "flag|--" /tmp/[repo]-research/src/cli

# Built-in modules
rg "Bun\.|Deno\.|node:" /tmp/[repo]-research

# Env vars
rg "process\.env|Deno\.env|Bun\.env" /tmp/[repo]-research

Output Focus

• CLI flags table
• Built-in APIs
• Node.js compatibility status
• Performance tuning options
• Environment variables

---

Databases/Services (D1, R2, Postgres)

Where to Look

src/
├── Query syntax
├── Connection options
├── Limits and quotas
├── Error codes
└── Migration tools

Key Searches

# Limits
rg "limit|max|quota" /tmp/[repo]-research

# Error codes
rg "error|Error" /tmp/[repo]-research --type ts -A 2

# Config
rg "config|options|settings" /tmp/[repo]-research

Output Focus

• Query syntax examples
• Config options table
• Limits/quotas table
• Error codes and fixes
• Migration patterns

---

Monorepo Navigation

Many tools live in monorepos. Quick navigation:

# Find the main package
ls /tmp/[repo]-research/packages/

# Find entry points
rg "\"main\":|\"bin\":" /tmp/[repo]-research/packages/*/package.json

# Find CLI entry
rg "#!/" /tmp/[repo]-research --type ts | head -5

---

Version Detection

# From package.json
jq '.version' /tmp/[repo]-research/package.json

# From Cargo.toml
grep '^version' /tmp/[repo]-research/Cargo.toml

# From git tag
git -C /tmp/[repo]-research describe --tags --abbrev=0

# Latest release via GitHub API
gh release view -R [org]/[repo] --json tagName

---

Changelog Mining

# Find changelog
ls /tmp/[repo]-research/CHANGELOG* /tmp/[repo]-research/HISTORY* 2>/dev/null

# Recent entries
head -100 /tmp/[repo]-research/CHANGELOG.md

# Search for breaking changes
rg -i "breaking|removed|deprecated" /tmp/[repo]-research/CHANGELOG.md

---

Test Mining

Tests often show real usage patterns:

# Find test files
fd "test|spec" /tmp/[repo]-research --type f

# Find integration tests
fd "integration|e2e" /tmp/[repo]-research --type d

# Search tests for patterns
rg "it\(|test\(|describe\(" /tmp/[repo]-research --type ts -A 5

Source Discovery And Pattern Extraction

Use this reference for codebase archaeology, software-tool research, codebase reports, or mining reusable implementation patterns across one or more repositories.

Discovery Order

1. Read the docs entry points first. 2. Find executable entry points: commands, handlers, jobs, hooks, or exported APIs. 3. Trace data flow from input to durable side effect. 4. Identify the core types and invariants that survive across layers. 5. Compare at least one working path with one edge path. 6. Only then summarize architecture, patterns, and risks.

Pattern Extraction

Record a pattern only when it has:

• At least two concrete examples or one canonical implementation.
• A name that describes behavior, not a file location.
• Preconditions that say when the pattern applies.
• Failure modes that say when the pattern should not be reused.
• A pointer to validation evidence.

Software Research Output

For external tools and libraries, write output in this order:

1. Current stable version and release date. 2. Supported command/API surface. 3. Config files, env vars, and hidden defaults. 4. Migration hazards and known issues. 5. Recommendation for this repo, including "do not adopt" when warranted.

Report Shape

## Summary
## Entry Points
## Core Flow
## Invariants
## Reusable Patterns
## Risks
## Open Questions

---

Source: Adapted from an external skill corpus / codebase-archaeology, codebase-pattern-extraction, codebase-report, and research-software. Pattern-only, no verbatim text.

Vibe Methodology

Core principles for AI-assisted development. "Vibe" = trust-but-verify.

---

The 40% Rule

Never exceed 40% context utilization.

• Checkpoint at 35%
• Reset via session restart or /research artifact
• More context ≠ better results (hallucination risk increases)

---

Three Levels of Verification

Default to L2. Upgrade to L3 for:

• Authentication/authorization
• Financial calculations
• Data persistence
• External API calls

---

Evidence Hierarchy

Trust in order:

1. Running code - Actually execute it 2. Tests - Passing tests prove behavior 3. File contents - Read the actual source 4. Documentation - May be stale 5. Model claims - Verify everything

---

Working Patterns

Incremental Verification

Write small piece → Test → Verify → Repeat

Don't write 500 lines then debug. Write 50, verify, continue.

Checkpoint Often

• After each feature complete
• Before any risky change
• At natural boundaries

Search Before Implement

# Always check for prior art
mcp__smart-connections-work__lookup --query="<topic>"
ls .agents/research/ | grep -i "<topic>"

---

Anti-Patterns to Avoid

---

The Research Discipline

1. Scope first - Define what you're looking for 2. Search smart - Use semantic search before grep 3. Read selectively - Don't load whole files 4. Cite everything - file:line for all claims 5. Synthesize - Connect findings to goal

---

Session Hygiene

# Start
gt hook              # Check assigned work
bd ready             # What's available

# Work
/research <topic>    # Creates artifact, saves context
/implement <issue>   # Focused execution

# End
bd vc status         # Optional Dolt status check; JSONL auto-sync is automatic
git commit           # Commit changes
git push             # WORK IS NOT DONE UNTIL PUSHED

---

References

• failure-patterns.md - 12 specific failure modes
• context-discovery.md - 6-tier exploration hierarchy
• ~/.claude/CLAUDE-base.md - Full vibe methodology

Validation Script for Research Skill

Overview

The validate.sh script ensures the /research skill meets basic quality and completeness standards. It runs a series of checks against the skill's structure, documentation, and references.

Purpose

This validation script serves as a quality gate for the research skill, ensuring:

• Required files exist with correct structure
• Documentation includes essential patterns and concepts
• References directory contains sufficient resource materials

Script Location

skills/research/scripts/validate.sh

Script Execution

The script performs the following checks:

Basic Structure Validation

• SKILL.md exists: Verifies the primary skill documentation file
• SKILL.md has YAML frontmatter: Ensures proper metadata formatting
• name: research: Confirms correct skill identification
• references/ directory exists: Validates reference materials directory
• references/ has at least 3 files: Ensures minimum reference coverage

Documentation Content Validation

• SKILL.md mentions .agents/research/ output path: Confirms documented output location
• SKILL.md mentions .agents/findings/registry.jsonl: Confirms the reusable-finding registry bridge
• SKILL.md mentions reusable findings: Ensures transient notes are not treated as durable registry entries
• SKILL.md mentions dedup_key: Confirms the merge key required by the registry contract
• SKILL.md mentions temp-file-plus-rename atomic write rule: Confirms the registry write semantics
• SKILL.md mentions finding-compiler.sh refresh: Confirms the follow-up compiler pass is documented
• SKILL.md mentions Explore agent: Ensures agent reference is included
• SKILL.md mentions --auto flag: Validates feature documentation
• SKILL.md mentions ao lookup or ao search: Checks CLI integration documentation
• SKILL.md mentions knowledge flywheel: Confirms system architecture coverage
• SKILL.md mentions backend detection: Validates technical implementation details
• SKILL.md mentions quality validation: Ensures quality assurance documentation

Usage

Manual Execution

# From the project root directory
./skills/research/scripts/validate.sh

Expected Output

PASS: SKILL.md exists
PASS: SKILL.md has YAML frontmatter
PASS: SKILL.md has name: research
PASS: references/ directory exists
PASS: references/ has at least 3 files
PASS: SKILL.md mentions .agents/research/ output path
PASS: SKILL.md mentions .agents/findings/registry.jsonl
PASS: SKILL.md mentions reusable findings
PASS: SKILL.md mentions dedup_key
PASS: SKILL.md mentions temp-file-plus-rename atomic write rule
PASS: SKILL.md mentions finding-compiler.sh refresh
PASS: SKILL.md mentions Explore agent
PASS: SKILL.md mentions --auto flag
PASS: SKILL.md mentions ao lookup or ao search
PASS: SKILL.md mentions knowledge flywheel
PASS: SKILL.md mentions backend detection
PASS: SKILL.md mentions quality validation

Results: 17 passed, 0 failed

Integration with CI/CD

This script can be integrated into continuous integration workflows to ensure the research skill meets quality standards before deployment:

# Example GitHub Actions workflow
- name: Validate Research Skill
  run: ./skills/research/scripts/validate.sh

Exit Codes

• 0: All checks passed (success)
• 1: One or more checks failed
• 2: Script execution error

Development Workflow

Adding New Features to Research Skill

1. Implement the feature in the skill's codebase 2. Update SKILL.md to document the new functionality 3. Run validation script to ensure documentation is complete:

   ./skills/research/scripts/validate.sh

4. Address any failures by updating documentation or code 5. Commit changes with confidence the skill meets quality standards

Updating Validation Criteria

To modify validation criteria:

1. Edit validate.sh to add/remove checks as needed 2. Update this documentation to reflect new validation requirements 3. Test the updated script against the current skill implementation

Research Skill Self-Test

Trigger Cases

• User says: /research "authentication system" (or any /research <topic>).
• Expected: load research, create .agents/research/, search prior art first, then dispatch an explore agent.

• User says: "investigate how the cache layer works and write up the findings."
• Expected: load research and produce a cited .agents/research/YYYY-MM-DD-<slug>.md artifact.

• User says: /research "payment processing flow" --auto.
• Expected: load research and run the full workflow without the Gate-1 human approval step.

Non-Trigger Cases

• User asks to implement or change code directly with no investigation request.
• Expected: do not load research; route to /implement or /plan.

• User asks for session/handoff history ("what did we decide last session?").
• Expected: use /recover, not research — research reads git commit history, not session history.

Behavior Checks

These map to the four scenarios in references/research.feature:

• Prior art is searched before fresh exploration: ao inject/lookup plus the .agents/ knowledge dirs run first, and applicable learnings are cited in the output (not just loaded passively).
• An explore agent is actually dispatched (not merely described) using the detected backend, and it uses iterative retrieval — score results, extract new terms from high-relevance hits, refine over up to 3 cycles.
• Findings are written to .agents/research/YYYY-MM-DD-<slug>.md, and every claim carries a file:line citation.
• Interactive runs request human approval (Gate 1) before reporting completion; --auto proceeds without the gate.

Validation Commands

Run from the repo root:

bash skills/heal-skill/scripts/heal.sh --strict skills/research
bash scripts/validate-skill-frontmatter.sh --strict

Failure Cases

• Explore agent only described, never dispatched: re-run and dispatch the agent (or perform the exploration inline if no spawn backend is available) — see the Key Rules in SKILL.md.
• Findings written without file:line citations: fail the artifact and re-cite every claim before reporting.
• Missing reference file linked from SKILL.md: fail heal validation and restore the file or remove the link.