h4tcher-capability-discover

name: h4tcher-capability-discover description: Pre-flight read-only scan for a planned capability change — maps what exists, what would collide, and which pillar gap a new artifact would close. effort: medium allowed-tools: Read Grep Glob Bash(*) WebSearch WebFetch triage_tiers: [1, 2, 3] parallel_tool_default: true cache_friendly: true quality_charter: agents/shared/quality-charter.md

Last updated: 2026-06-06

Capability Discover (Maintainer, Read-Only)

Investigative preset. Run first when scoping any add / refactor / remove. Produces a structured report; writes no files in the repo. Workspace files under .audit-workspace/ are allowed for T2/T3 sub-agent slices.

Step 0: Triage

Classify the request before any scan:

• T1 — single artifact type in scope (e.g., "is there already an agent for X?"). Inline scan; skip Step 4.
• T2 — 2-3 artifact types or one cross-reference dimension. 3 parallel sub-agents per Step 4.
• T3 — multi-pillar surface (e.g., touches agents + adapters + governance). 3 parallel sub-agents per Step 4 plus pillar-gap analysis.

Record the tier in the Step 7 report header.

Step 1: Preflight

1. Confirm clean working tree: git status --short returns empty.
2. Cache governance lean limits from governance/CONSTITUTION.md §2 P5.
3. Resolve target artifact type(s) from the prompt: agent, skill, rule, command, hook, adapter, pipeline module, governance file.
4. Note current branch: git branch --show-current.

Step 2: Discover / Duplication Scan

5. Read governance/inventory.json — extract counts and ids for each artifact directory.
6. Grep across the canonical content surface for the target intent's keywords:

   grep -RIn --include='*.md' '<keyword1>\|<keyword2>' \
     agents/ skills/ rules/ commands/ hooks/ \
     checks/ prompts/ github-agents/ \
     src/adapters/ src/content/
   

7. Cross-check candidates against the D16.3 overlap criteria in governance/audit/domains/D16-compound-system.md (definition + add-vs-remove bias check). Record each candidate's overlap dimension (purpose / scope / pillar / referenced files) and a rough percentage estimate.
8. Count inbound cross-references for each candidate via grep -RIn "<candidate-id>" across the same surface plus governance/, docs/, docs-site/, tests/, CLAUDE.md, README.md, CHANGELOG.md.

Step 3: Web Research

Per agents/shared/rigor-contract.md §"Web Research Mandate": ≥2 independent sources, trust tier (official-docs > peer-reviewed > vendor-note > independent-analysis > blog-post), recency window (≤90 days for CVE, ≤12 months for vendor docs, ≤36 months for peer-reviewed). Sources recorded in Step 7. Skip when no empirical claim is being investigated (most pure-overlap scans).

Step 4: Sub-Agent Dispatch (T2 / T3 only)

Spawn 3 parallel Task sub-agents. Slice the surface so file scopes are disjoint:

Each sub-agent prompt MUST include: discovery slice from Step 2, the h4tcher-development context block (pillar test, lean thresholds, anti-slop wordlist ref, commit format) modeled on .claude/skills/h4tcher-pr-resolve/SKILL.md, the confidence-with-basis requirement from the rigor contract, and an explicit "no branches, no commits, no PRs, read-only" guardrail. T1 skips this step entirely.

Fan-out is task-derived (P8 B2): 0 sub-agents on T1, 3 on T2/T3. Token cost never serializes independent work (.claude/rules/fan-out-discipline.md Cost-dominance clause). Emit sub_agents_spawned: { count, rationale } in your output (the Sub-agents field of the Step 7 report).

Step 5: Cross-Skill Delegation

None. This preset is purely investigative — no delegation to h4tcher-content-author, h4tcher-adapter-author, or h4tcher-domain-author. The Step 7 report's "recommended next preset" field tells the maintainer which lifecycle preset to invoke next.

Step 6: Governance Gates (light)

9. Re-read the report draft; remove any banned anti-slop phrase before emission (wordlist mirrored in CLAUDE.md and .claude/rules/anti-slop-enforcement.md).
10. wc -l the rendered report — hard ceiling 150 lines (target 80).
11. Verify every duplication candidate cites a concrete file path (with line number when relevant).
12. Skip npm run validate / npm test — this preset writes nothing to the repo.

Step 7: Output (Capability Discovery Report)

Emit in chat using this exact template:

Capability Discovery Report
---------------------------
Tier: T1 | T2 | T3
Target intent: <one line — what the maintainer is scoping>
Candidate types: <agent | skill | rule | command | hook | adapter | pipeline | governance>
Pillar(s) served: P<n>[, P<n>, ...]

Duplication candidates (K):
  <file:line> — <overlap dimension> — <est. overlap %>
  ...

Cross-reference impact: <total inbound references across candidates>
Pillar coverage delta: <gap closed | gap unchanged | risk of redundant coverage>
Sub-agents: count=<0|3>, rationale=<one-line task-decomposition justification>

Recommended next preset: <h4tcher-capability-add | h4tcher-capability-refactor | h4tcher-capability-remove | no action | h4tcher-scoped-audit>

Sources (if Step 3 ran): <per-claim citations with trust tier + recency>
Confidence: high | medium | low — <basis: source count, overlap signal strength>

No files written to the repo; workspace slices remain under .audit-workspace/.