| 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.
| Tier | Criteria | Pipeline |
|---|
| T1 | Leaf artifact with 0 inbound references | Inline; skip Step 4; full Step 6 gates |
| T2 | Artifact with 1-3 references requiring migration notes | 1-3 parallel sub-agents; full gates |
| T3 | Artifact named in any agentPipeline: array, listed in governance/inventory.json registry, or referenced from governance/CONSTITUTION.md / governance/VISION.md | >=3 parallel sub-agents; full gates + CL-3 flag if D16/AUDIT touched |
Record tier + rationale at the top of the workspace summary.
Step 1: Preflight
- Confirm clean tree + branch:
git status --short empty; git branch --show-current matches an open release/feature branch.
- Cache lean-threshold limits from
governance/CONSTITUTION.md §2 P5.
- Identify the target artifact type (agent | skill | rule | command | hook | adapter | pipeline module) and its canonical path.
- 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:
| Slot | Role |
|---|
| migration-notes | Drafts the CHANGELOG.md entry (under ### Removed) plus an optional docs-site/ deprecation page when an end-user-visible artifact is removed |
| refs-canonical | Scrubs references in agents/ skills/ rules/ commands/ hooks/ checks/ prompts/ github-agents/ |
| refs-code-docs | Scrubs references in src/, tests/, governance/, docs/, docs-site/, CLAUDE.md, README.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, task_structure } in your output (the Sub-agents field of the Step 7 summary; task_structure: parallelizable — the migration-notes / refs-canonical / refs-code-docs slots are disjoint).
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.
| Gate | Command | Threshold |
|---|
| Validate | npm run validate | 0 errors |
| Tests | npm test | 0 failed |
| Typecheck | npx tsc --noEmit | 0 errors |
| Lint | npm run lint | 0 errors |
| Build | npm run build | succeeds; dist/ produced |
| Rule parity | npm run validate:rule-parity | 0 mismatches |
| Efficiency invariants | npm run validate:efficiency | 0 violations |
| Inventory regen | npm run inventory then git diff governance/inventory.json | diff matches the removal exactly; no unexpected drift |
| Inventory docs drift | npm run inventory:check-docs | 0 drift |
| Reference-orphan check | grep -rn "<removed-name>" agents/ skills/ rules/ commands/ hooks/ checks/ prompts/ github-agents/ src/ governance/ docs/ docs-site/ tests/ CLAUDE.md README.md CHANGELOG.md | 0 hits outside the CHANGELOG migration entry |
| CHANGELOG entry | grep -n "<removed-name>" CHANGELOG.md | >=1 line under the active release's ### Removed section |
| Anti-slop | grep -nE against .claude/rules/anti-slop-enforcement.md wordlist on every modified .md / .mdc | 0 hits |
| Pillar compliance | Apply .claude/rules/pillar-compliance.md to the removal | Removal serves one or more of P1-P8 |
| Lean thresholds | wc -l on every modified governance file | Within CONSTITUTION §2 P5 limits |
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
