hunt

name	hunt
description	Systematic work discovery — scan TODO, architecture, cogarch, ideas, lessons for highest-value next work.
user-invocable	true
argument-hint	[all | orthogonal | stale | quick | blocked | cogarch | ideas | extrapolate]
allowed-tools	Read, Write, Edit, Grep, Glob, Bash

Hunt — Systematic Work Discovery (Psychology Agent)

Find the highest-value next work in the psychology agent project. Aggregates all the ways you'd search for "what's next" into one structured sweep.

---

Trigger Phrases

This skill matches any of these user intents:

• "what's next?" / "what else?" / "what can we do?"
• "look for orthogonal work" / "find stale work"
• "anything to do while we wait?"
• "what should I focus on?" / "what's highest value?"
• "find work at the edges of context"

---

Arguments

Parse the argument to determine scope:

Argument	Constraint
(empty) or all	Full sweep — all sources, rank by value
orthogonal	Only surface work that doesn't touch files being modified
stale	Focus on drift and rot — stale docs, dead references
quick or quick wins	Only items that take <5 minutes
blocked	Show what's blocked and what would unblock it
cogarch	Focus only on cognitive architecture consistency
ideas	Surface ideas.md items ready to act on
extrapolate / deep	Go beyond the backlog — mine design/research gaps

Multiple constraints can be combined: orthogonal quick wins

If argument doesn't match any keyword, treat it as a domain/topic filter: run the full sweep but surface only items relevant to that topic. If truly ambiguous, default to full sweep and note the interpretation at the top.

---

Phase 1: Establish Context

Before hunting, understand what's currently in-flight:

1. Read TODO.md — canonical task backlog
2. Run TaskList — active task tracker (in-progress = in-flight)
3. Read lab-notebook.md Current State block — open questions, pending items
4. Read MEMORY.md from auto-memory (the platform loads this automatically) — active thread, cogarch quick-reference, working principles
5. Glob .claude/plans/*.md — existing plans (may have unfinished work)
6. Epistemic debt summary — run python3 scripts/epistemic_debt.py --summary to get the current unresolved uncertainty count. High debt sessions or agents may warrant targeted resolution work.

Build a mental model of: what's active, what's done, what's blocked, what's untouched.

---

Phase 2: Scan Sources

Work through each source. For each, extract candidate work items with a rough value estimate.

Source 1: TODO.md Backlog

• Extract all unchecked - [ ] items
• Note dependencies (does completing item X unblock item Y?)
• Flag items whose prerequisites are now met
• Note items that have been sitting without a blocking reason — these may be stale

Source 2: Task List

• Check for pending tasks not yet started
• Check for blocked tasks whose blockers may have resolved
• Check for stale in-progress tasks (started but abandoned)

Source 3: Stale Plans

• Glob .claude/plans/*.md
• For each plan, check if it has unfinished items
• Skip plans clearly superseded by current architecture decisions

Source 4: Architecture Gaps

The most common form of drift in design-phase projects: decisions are documented but their downstream specifications don't exist yet.

• Read docs/architecture.md — for each resolved decision, check whether the corresponding spec, skill, or implementation exists
• Architecture items with ✗ status in lab-notebook.md Current State — these are explicitly deferred; note what's blocking each
• Cross-reference architecture.md ↔ cogarch — does the documented authority hierarchy, Socratic protocol, and staged hybrid spec have trigger coverage in cognitive-triggers.md?

Source 5: Documentation Drift

• MEMORY.md volatile state vs. reality — check the Active Thread against lab-notebook.md; are they consistent?
• journal.md ToC vs. actual sections — does every ToC entry have a corresponding section? Do notable decisions have journal entries?
• lab-notebook.md Open Questions — have any been answered since the last update? Check architecture.md and conversation context.
• ideas.md — are any ideas now actionable (prerequisite met, decision resolved)? Flag items that have drifted past their stated precondition.
• MEMORY.md → CLAUDE.md migration — stable conventions that belong in CLAUDE.md rather than MEMORY.md create line pressure. Identify candidates.
• lessons.md.example vs. lessons.md — does the template match the actual format being used? Any format drift?

Source 6: Cogarch Consistency

This is the T11 audit as a hunt source — always run, even for quick constraint.

• Read docs/cognitive-triggers.md — check each trigger (T1–T12) for:
  • Missing coverage: a working principle in MEMORY.md with no corresponding trigger
  • Contradictions: trigger says X, another says Y for same situation
  • Orphaned triggers: trigger fires on a condition that no longer exists
  • Missing failure analyses: T11 findings with no future mitigation entry
• Principles in MEMORY.md without triggers: scan "Working Principles" section and cross-check each against cognitive-triggers.md
• Socratic discipline coverage: are "evidence before conclusion" and "competing hypotheses" triggered in the right places?
• Recommend-against coverage: is the recommend-against check (T3) consistently applied across all default-action triggers?

Source 7: Skills Inventory

• Glob .claude/skills/**/*.md in project root — what skills exist?
• Cross-reference against TODO.md — which skills are planned but not yet created?
• Check PSQ sub-project skills — are there skills in safety-quotient/.claude/skills/ that are being invoked from the psychology agent context without a psychology-agent adaptation? (The PSQ /hunt and /cycle skills contain PSQ-specific logic; a caller from the psychology agent context gets the wrong behavior.)
• Test each skill — skills created mid-session don't load until restart; flag any skill that hasn't been verified post-creation.

Source 8: Cross-Reference Rot

# References to files that might have been renamed or not yet created
PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
grep -r "SKILL\.md\|architecture\.md\|cogarch\|cognitive-triggers" \
     "${PROJECT_ROOT}"/*.md \
     "${PROJECT_ROOT}"/docs/*.md \
     "${PROJECT_ROOT}"/.claude/skills/**/*.md \
     2>/dev/null | grep -v "^Binary"

• Check for references to files that don't exist
• Check for internal links in journal.md and architecture.md that point to missing sections
• Check BOOTSTRAP.md step sequence against what files actually exist

---

Phase 2b: Deep Extrapolation (for extrapolate / deep constraint)

When asked to "extrapolate" or "go deeper than the backlog," scan three layers:

Layer 1: Design → Specification Gaps

What does the architecture call for that has no specification yet?

• Psychology agent identity spec — architecture.md says "collegial mentor, Opus, Socratic, dynamic calibration." Has this been written as a prompt/system spec? What's the actual first-message behavior?
• Sub-agent communication standard — staged hybrid Stage 1 requires a comm standard (output format, scope declaration, limitation disclosure). Is it written?
• Adversarial evaluator spec — tiered activation and parsimony reasoning are documented. Is there a draft prompt or decision procedure?
• Machine-to-machine detection spec — "structural detection" is the approach. What are the specific signals? Is this operationalized anywhere?
• Voice protocol — ⚡ output format specification was flagged but not closed. Where does this belong? (CLAUDE.md? architecture.md? A new voice-protocol.md?)

Layer 2: Lessons → Trigger Coverage Gaps

Each lesson should eventually have trigger coverage preventing the error from recurrence.

• Read lessons.md — for each lesson, check whether the "The tell" or "The diagnostic" is operationalized in a cognitive-trigger.
• Lessons without trigger coverage are known vulnerabilities.
• Flag the highest-value uncovered lessons (those marked under "Domains where this recurs" that overlap directly with this project's work).

Layer 3: Ideas → Research Direction Gaps

• Read ideas.md — for each idea marked as a research direction rather than a task, check what evidence or precondition would move it from speculation to action.
• Identify ideas that are now feasible (prerequisite resolved) but haven't been promoted to TODO.md.
• Identify ideas that should be retired (superseded by architecture decisions).

Presenting extrapolation results

Organize into two buckets:

1. New TODOs — concrete gaps that should be fixed (missing spec, orphaned reference, lesson without trigger coverage)
2. New IDEAS — enhancement opportunities (new validation approach, new research direction, new skill design)

For each finding: what it is, where (file:section or memory location), severity/value, and effort estimate.

---

Phase 3: Classify & Rank

For each candidate, assign:

Value Rating

• HIGH: Unblocks architecture work, fixes a cogarch inconsistency, enables a missing spec, or fixes a skill that's being invoked incorrectly
• MED: Improves documentation completeness, fills an ideas/lessons gap, cleans stale state
• LOW: Style improvements, minor reorganizations, nice-to-have analyses

Effort Rating

• XS: <2 minutes (delete a reference, fix a typo, update a date)
• S: 2–10 minutes (single-file doc update, add a trigger, update MEMORY.md entry)
• M: 10–30 minutes (new spec section, skill adaptation, multi-file update)
• L: 30+ minutes (full skill creation, architecture item, new research section)

Orthogonality

• SAFE: Doesn't touch any in-flight files
• ADJACENT: Touches related but not identical files
• OVERLAPPING: Would conflict with in-flight work — defer

---

Phase 4: Present Results

## Hunt Results

**Context:** [1-line summary of what's in-flight and constraint applied]
**Active thread:** [from MEMORY.md Active Thread]

### Top Picks (recommended next)
1. **[Subject]** — [1-line description]
   Value: HIGH | Effort: S | Where: `path/to/file` or section

2. **[Subject]** — [1-line description]
   Value: MED | Effort: XS | Where: `path/to/file`

### Backlog Candidates (from TODO.md)
- **[Item]** — [status/blocker note]

### Stale Items (needs attention)
- **[Item]** — [why stale, what to do]

### Cogarch Findings
- **[Trigger/principle]** — [inconsistency or gap]

### Blocked (needs unblocking first)
- **[Item]** — blocked by: [what]

Presentation Rules

• Max 10 items in Top Picks — don't overwhelm
• Bold the subject, keep descriptions to one line
• Always include effort estimate — "this is 2 minutes" vs "this is 30 minutes" matters
• Group by theme if multiple items relate (e.g., "3 stale doc entries" = 1 item, not 3)
• Process vs. substance distinction: Ordering and sequencing decisions (which of three items to do first, where to put a section) → resolve autonomously and present the plan. Direction decisions (what gets built, what approach, what priority) → surface to user with recommendation.
• Recommend-against check: Before presenting any item, scan for a specific concrete reason not to surface it. Vague concern doesn't count. If no specific objection → include it.
• End with a recommendation: "I'd suggest starting with #1 because [reason]"

---

Phase 5: Decision Refinement

When hunt surfaces items requiring a choice between approaches (not just "do this"), shift into decision-assist mode. This applies to:

• Items with multiple implementation strategies
• Deferred items where the decision is "do it now / later / never"
• Architecture decisions (new spec vs. defer, which approach to use)
• Any item where the user says "what do you think?" or hasn't committed

Step 1: Identify 2–3 distinct options

Frame as concrete, mutually exclusive choices. Not vague ("maybe improve cogarch") — specific ("add trigger now" vs. "defer until T11 next audit" vs. "retire as unnecessary").

Step 2: Classify the decision domain

Domain	Signal	Effect vectors
Architecture	adding/changing a spec or decision	architecture.md → cogarch → skills → sub-agent protocol
Cogarch	adding/changing a trigger	cognitive-triggers.md → behavior → MEMORY.md → lessons.md
Documentation	updating or deferring doc changes	reproducibility → future context → /cycle checklist
Skills	creating/adapting a skill	.claude/skills/ → invocation behavior → context management
Research scope	adding/removing an architecture item	design depth → TODO.md → session planning

Step 3: Ground the analysis

Before asking questions or tracing effects, read relevant files or sections to verify what the changed thing actually does and what depends on it.

Step 4: Ask clarifying questions

Use AskUserQuestion with targeted questions that would change which option is best.

Step 5: Knock-on cascade — for each option

Invoke /knock for each option. Use inline for XS/S decisions, full for M/L. See .claude/skills/knock/SKILL.md for the full 10-order protocol, confidence discipline, and output format.

After each cascade, list key mitigations and assumptions.

Step 6: Comparison table

	Architecture value	Effort	Reversibility	Cogarch consistency	Risk
Option 1	...	...	...	...	...
Option 2	...	...	...	...	...

Pick only axes that differentiate the options.

---

Phase 6: Offer Next Steps

After presenting results (and completing Phase 5 decision refinement if needed):

If Phase 5 was run: Lead with winning option or ask user to confirm, then offer to execute. Don't re-list items Phase 5 already resolved.

Board status update: When the user selects an item to work on, mark it In Progress on the GitHub Projects board:

python3 scripts/sync_project_board.py --mark-in-progress "{item title}"

This runs silently — no need to report the status change to the user.

If Phase 5 was skipped (straightforward tasks), offer:

• "Want me to tackle #1–3 (quick wins)?"
• "Want me to draft the [spec] for architecture item 1?"
• "Want me to add trigger coverage for [lesson]?"
• "Want me to run /doc to persist these findings before we move on?"

If no meaningful work is found: "Project is in good shape. Next meaningful work is [item], which requires [prerequisite]."

---

Efficiency Notes

Skip matrix — which sources to run per constraint:

Constraint	Sources to run	Sources to skip
(empty) / all	1–8 + Phase 2b	—
quick / quick wins	1, 2, 6 (cogarch only)	3, 4, 5, 7, 8, Phase 2b
stale	3, 4, 5, 8	1, 2, 6, 7, Phase 2b
blocked	1, 2	3–8, Phase 2b
orthogonal	1–8 (filter by SAFE)	Phase 2b
cogarch	6 only + Phase 2b L2	1–5, 7, 8
ideas	5 (ideas.md only), 2b L3	1–4, 6–8
extrapolate / deep	1, 2, Phase 2b	3–8 (maintenance)

Other notes:

• Source 6 (cogarch) is always run — even for quick. A missed trigger is a live vulnerability regardless of session constraints.
• Parallel reads where possible: Sources 1, 3, 5, 7 can all be read concurrently.
• Process decisions within the hunt (ordering Top Picks, grouping stale items) → resolve autonomously. Only surface substance questions.
• Don't re-scan what was already found in the same session.