h4tcher-capability-refactor

name: h4tcher-capability-refactor description: Rename, split, merge, or restructure an existing canonical artifact with cross-reference scrubbing and an explicit rename-map deliverable. 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 Refactor (Maintainer)

Lifecycle preset for renaming, splitting, merging, or restructuring an existing artifact (agent, skill, rule, command, hook, adapter, pipeline module, governance file). Owns the cross-reference scrubber. Stops before commit so the maintainer reviews the rename map and diff.

§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 (rename vs split vs merge unclear, or which artifact is the target), (b) multiple valid interpretations with materially different cross-reference blast radius, (c) irreversible action (public artifact id rename, frontmatter-field drop, agentPipeline: member rename), or (d) missing acceptance criteria (no rename map, 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 refactor scope first:

• T1 — body restructure only; no rename; no cross-reference impact. Inline; skip Step 4.
• T2 — rename of one artifact with ≤10 cross-references. 3 parallel sub-agents per Step 4.
• T3 — split / merge, agentPipeline: impact, or rename touching governance/inventory.json registry plus governance/CONSTITUTION.md references. ≥3 parallel sub-agents per Step 4; CL-3 flag if D16 or AUDIT files touched.

Record the tier in the Step 7 summary header.

Step 1: Preflight

1. Confirm clean working tree: git status --short returns empty.
2. Confirm branch: git branch --show-current.
3. Cache governance lean limits from governance/CONSTITUTION.md §2 P5 for any governance file the refactor will touch.
4. Resolve the target artifact: file path, id, type (agent | skill | rule | command | hook | adapter | pipeline | governance).
5. Capture baseline wc -l for the target plus every governance file near the lean threshold.

Step 2: Discover (Cross-Reference Scan)

6. Run the canonical cross-reference scan against the old name or id. Substitute <old-name> with the artifact id (e.g., hatch3r-fixer):

   grep -r "<old-name>" agents/ skills/ rules/ commands/ hooks/ checks/ prompts/ github-agents/ src/ governance/ docs/ docs-site/ tests/ CLAUDE.md README.md CHANGELOG.md
   

7. Read governance/inventory.json to enumerate every registry citation of <old-name> (ids field, managedFiles paths, counts).
8. For agent renames, list every commands/hatch3r-*.md whose frontmatter agentPipeline: array contains <old-name> — these orchestrator commands resolve the agent by id, so any miss leaves a broken pipeline.
9. Bucket every hit into one of three surfaces: code/tests (src/, tests/, scripts/), governance/docs (governance/, docs/, docs-site/, CLAUDE.md, README.md, CHANGELOG.md), canonical artifacts (agents/, skills/, rules/, commands/, hooks/, checks/, prompts/, github-agents/).

Step 3: Web Research

Skip for pure rename or in-file restructure with no empirical claim. Required when the refactor adopts a new industry pattern (e.g., restructuring an adapter around a vendor's new feature surface). 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 (≤90d CVE, ≤12mo vendor docs, ≤36mo peer-reviewed). Sources recorded in Step 7.

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

Spawn 3 parallel Task sub-agents. Each updates references on its disjoint surface slice and writes a diff manifest:

Each sub-agent prompt MUST include: the slot's bucket 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, confidence-with-basis per the rigor contract, the workspace target path, and an explicit "no branches, no commits, no PRs" guardrail.

Fan-out is task-derived (P8 B2): 0 sub-agents on T1 (inline), 3 on T2/T3 across the disjoint reference-surface slices 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

Body-content rewrites delegate to the matching author skill — set up context only, do not author inline:

The orchestrator retains: rename-map authorship, Step 4 sub-agent coordination, Step 6 gates, Step 7 summary.

Step 6: Governance Gates

10. Run the full gate battery, blocking on any failure:

    npm run validate && npm test && npx tsc --noEmit && npm run lint && \
      npm run build && npm run validate:rule-parity && npm run validate:efficiency
    

11. Reference-orphan check. Re-run the Step 2 grep command against the post-refactor tree. Hit count MUST be zero for the old name:

    grep -r "<old-name>" agents/ skills/ rules/ commands/ hooks/ checks/ prompts/ github-agents/ src/ governance/ docs/ docs-site/ tests/ CLAUDE.md README.md CHANGELOG.md | wc -l
    

12. Regenerate the registry and inspect the diff:

    npm run inventory
    git diff governance/inventory.json
    

    The diff must reflect every renamed id; investigate any unexpected drift before proceeding.
13. Anti-slop scan on every modified .md / .mdc file using the wordlist regex from .claude/rules/anti-slop-enforcement.md; any hit blocks commit and is fixed via that file's replacement column.
14. Pillar Compliance Test (.claude/rules/pillar-compliance.md) on every modified file; lean threshold check against the Step 1 baselines.

Step 7: Stop-Before-Commit Summary

15. Emit the summary below to the conversation. Do not commit, push, or merge.

Capability Refactor Summary
---------------------------
Tier:      T1 | T2 | T3
Branch:    <branch>
Target:    <old id / path>  ->  <new id / path>
Refactor:  rename | split | merge | restructure

Rename map: <old-id> -> <new-id> (one row per artifact)

Reference updates: code/tests <n> | governance/docs <n> | canonical <n> | total <n>
Inventory delta: <managedFiles +/-, ids +/-, manifest checksum changed yes/no>
Reference-orphan grep hits on old name: <count> (must be 0)

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>
  Anti-slop hits                 <count> (must be 0)

Pillars served: P<n>[, P<n>, ...]
Lean threshold deltas: <file: before -> after / limit>
Sub-agents: count=<0|3>, rationale=<one-line task-decomposition justification>
Sources (if Step 3 ran): <per-claim citations with trust tier + recency>

Suggested commit message:
  refactor(<scope>): <old-id> -> <new-id>

  <body line 1>
  <body line 2>

  Pillars: P<n>, P<n>

Status:     SUCCESS | PARTIAL | BLOCKED
Confidence: high | medium | low

Next action (run manually):
  git add <files>
  git commit -s -m "<suggested message>"

References

• Cross-skill: .claude/skills/h4tcher-content-author/SKILL.md, .claude/skills/h4tcher-adapter-author/SKILL.md, .claude/skills/h4tcher-domain-author/SKILL.md
• Triage skeleton: .claude/skills/h4tcher-pr-resolve/SKILL.md
• Web research mandate: agents/shared/rigor-contract.md
• Anti-slop wordlist: .claude/rules/anti-slop-enforcement.md
• Pillar Compliance Test: .claude/rules/pillar-compliance.md