h4tcher-capability-remove

name: h4tcher-capability-remove description: Decommission a hatch3r artifact (agent, skill, rule, command, hook, adapter, pipeline module) after passing the D16.3 removal-threshold gate, drafting migration notes, and scrubbing every cross-reference. effort: high allowed-tools: Read Grep Glob Bash(*) Write Edit Task 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 Remove (Maintainer)

Maintainer preset for phasing out a hatch3r artifact. Hardest preset to invoke: a D16.3 gate blocks removal unless three criteria all hold, and migration notes plus reference scrubbing run before the maintainer is allowed to commit.

§0.1: Ambiguity Gate (P8 B1)

Per CONSTITUTION §2 P8 B1: every framework-dev workflow mutating canonical artifacts detects and resolves ambiguity via agents/shared/user-question-protocol.md BEFORE executing — default behavior, not exception-driven. Apply the protocol when any hold: (a) ambiguous scope (which artifact, and remove vs merge-then-deprecate per D16.3 add-vs-remove bias), (b) multiple valid interpretations with materially different migration cost, (c) irreversible action — removal is inherently destructive, so confirm the target id and that no consumer depends on it, or (d) missing acceptance criteria (no migration-note target, no definition of done). Use the platform-native question tool; one question per turn; 2-4 numbered options with one-line trade-offs; declare the default-if-no-response. Do NOT proceed to Step 0 until resolved or the default is confirmed.

Step 0: Triage

Classify the removal target before any work runs.

Record tier + rationale at the top of the workspace summary.

Step 1: Preflight

1. Confirm clean tree + branch: git status --short empty; git branch --show-current matches an open release/feature branch.
2. Cache lean-threshold limits from governance/CONSTITUTION.md §2 P5.
3. Identify the target artifact type (agent | skill | rule | command | hook | adapter | pipeline module) and its canonical path.
4. Capture baseline wc -l on governance/inventory.json and any governance file likely to be edited.

Step 2: Removal-Qualification Gate (D16.3)

Run the D16.3 removal-threshold check inline (governance/audit/domains/D16-compound-system.md §16.3 "Removal candidate threshold"). Removal qualifies only when ALL three criteria hold:

• (a) Zero unique value beyond an existing artifact (run duplication scan; cite the artifact that subsumes the candidate).
• (b) <=1 cross-reference from other artifacts (run grep -r "<artifact-id>" agents/ skills/ rules/ commands/ hooks/ checks/ prompts/ github-agents/ src/ governance/ docs/ docs-site/ tests/ CLAUDE.md README.md CHANGELOG.md; record the count).
• (c) No orchestrator dependency in any commands/hatch3r-*.md agentPipeline: array (grep -l "<artifact-id>" commands/hatch3r-*.md; inspect each match).

Cite which criterion is crossed for every failing check. Block immediately on any failure and recommend /h4tcher-capability-refactor (merge) per the D16.3 add-vs-remove bias check.

Step 3: Web Research

Skipped by default. Run only when the removal cites an external "industry has deprecated this" claim. When triggered, follow the rigor contract (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 (<=90d CVE, <=12mo vendor docs, <=36mo peer-reviewed). Sources land in the Step 7 summary.

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

T1 stays inline (single scrub + one CHANGELOG line). T2/T3 dispatch parallel Task agents writing to .audit-workspace/capability-remove-{slot}.md:

Every sub-agent prompt MUST carry: (1) the Step 2 discovery slice (paths + ref counts), (2) the verbatim h4tcher-development context block from .claude/skills/h4tcher-pr-resolve/SKILL.md Step 2 (pillar test, lean thresholds, anti-slop wordlist reference, commit format), (3) the confidence-with-basis requirement from the rigor contract, (4) the "no branches, no commits, no PRs" guardrail, (5) the workspace write target above.

Fan-out is task-derived (P8 B2): 0 sub-agents on T1 (inline), 1-3 on T2, >=3 on T3 across the migration-notes / refs-canonical / refs-code-docs slots above. 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 summary).

Step 5: Cross-Skill Delegation

None for body authoring during removal. The migration-notes slot may call /h4tcher-content-author only when a brand-new replacement artifact must be authored — rare; document the rationale in the workspace summary when invoked.

Step 6: Governance Gates

Run the full hatch3r gate battery PLUS removal-specific checks. Block commit on any failure.

Step 7: Stop-Before-Commit Summary

Emit the slot-filled template below. Do not commit, branch, push, or merge.

Capability-Remove Summary
-------------------------
Artifact:           <id / path>
Type:               agent | skill | rule | command | hook | adapter | pipeline-module
Tier:               T1 | T2 | T3
D16.3 criteria:     (a) <pass + cite subsuming artifact> (b) <ref count <=1> (c) <no agentPipeline hit>

Removed paths:      <bullet list>
Migration notes:    CHANGELOG.md (line <n>, ### Removed) [+ docs-site/<page>.md if authored]
agentPipeline diffs: <command file: before -> after, or "none">
Inventory delta:    <line counts: before -> after in governance/inventory.json>

Gates:
  npm run validate                <PASS|FAIL>
  npm test                        <PASS|FAIL>
  npx tsc --noEmit                <PASS|FAIL>
  npm run lint                    <PASS|FAIL>
  npm run build                   <PASS|FAIL>
  npm run validate:rule-parity    <PASS|FAIL>
  npm run validate:efficiency     <PASS|FAIL>
  npm run inventory:check-docs    <PASS|FAIL>
  Reference-orphan grep           <PASS (0 hits) | FAIL>
  CHANGELOG entry present         <PASS | FAIL>
  Anti-slop hits                  <count — 0 required>

Pillars served:     P<n>, P<n>
Sub-agents:         count=<0|1-3|>=3>, rationale=<one-line task-decomposition justification>
Sources (web):      <list, or "none — no empirical claim">
Confidence:         high | medium | low

Next action (maintainer runs manually):
  git add <files>
  git commit -s -m "refactor(<scope>): remove <artifact-id>"
  git push

Constraints

• Block on any D16.3 failure in Step 2; do not proceed without the maintainer's explicit override + recorded rationale.
• Never hand-edit governance/inventory.json — only via npm run inventory.
• Do not skip the reference-orphan grep; one orphan hit blocks commit.
• Do not commit, branch, push, or merge from inside this skill.
• DCO sign-off via git commit -s is required when the maintainer commits.

References

• D16.3 removal-threshold + add-vs-remove bias check: governance/audit/domains/D16-compound-system.md §16.3 "Removal candidate threshold"
• Web research mandate: agents/shared/rigor-contract.md
• Quality charter: agents/shared/quality-charter.md
• Sibling presets: .claude/skills/h4tcher-capability-discover/SKILL.md, .claude/skills/h4tcher-capability-refactor/SKILL.md
• Author skill (replacement artifact, rare): .claude/skills/h4tcher-content-author/SKILL.md