[#313] refactor: progressive disclosure for implement/review/bootstrap (task T5)

[rucka]

Summary

What Changed

Task T5 of story #313 (own PR — each #313 task ships on its own branch/PR per the story's established pattern: T1/T2/T3/T4/T7/T8). Applies progressive disclosure to the 3 orchestrators (implement 423, review 391, bootstrap 314 lines): SKILL.md keeps steps + HALT + core rules on top; bulky branch-gated reference material moves into named sibling files behind sharply-worded context pointers.

Why This Change

AC5 of #313: the 3 orchestrators kept HALT conditions ~380 lines away from the phases they govern, with zero progressive disclosure across the corpus. Pushing reference-only material that a minority of runs ever reach (a specific degradation level, a re-invocation-only merge phase, an installed-optional-skill orchestration detail) into sibling files keeps the top of each SKILL.md — the part every run needs — readable.

Story Context

Story: #313 — Skill corpus effectiveness. Task: T5 (checklist item in the story body).
Acceptance Criteria: AC5 (SKILL.md leads with steps/HALT/core rules; bulky reference disclosed behind sharp pointers; install pipeline ships multi-file skill dirs or the CLI gap is fixed in-story).

Prerequisite check (gates the whole approach)

Verified whether pair-cli's install/mirror pipeline (flatten + prefix, packages/content-ops) ships a multi-file skill dir correctly, per the story's Edge Case rule.

Result: mostly worked, one real gap found and fixed (CLI extended in-story — small/contained, per the rule).

• Built a fixture (temp multi-file skill dir: SKILL.md + sibling .md files) and ran it through the real pipeline (copyPathOps with flatten+prefix, and the full handleInstallCommand path with a deep node_modules-style dataset root, mirroring production).
• Works: collectFiles in copy-directory-transforms.ts already recurses the whole skill directory (not just SKILL.md) and copies every sibling file to the transformed target dir — multi-file skill dirs ship.
• Broken (found via the fixture, confirmed failing before the fix): same-directory sibling cross-references (e.g. SKILL.md → ./edge-cases.md) were rewritten to a stale dataset-relative path (../../.skills/process/implement/edge-cases.md) instead of staying ./edge-cases.md. Root cause: link-rewriter.ts's reRootTarget (built for links escaping the skill dir into the wider KB, e.g. .pair/adoption/...) was also being applied to links resolving inside the very directory this copy operation is moving — the two link-rewriting concerns weren't distinguished.
• Fix: added rebaseWithinMovedDir — same-directory links now rebase 1:1 onto the new directory (priority over the coarser dataset-root re-root), which escaping links still use unchanged. ~25 lines, packages/content-ops/src/ops/link-rewriter.ts.
• Both fixture regression tests are now permanent: packages/content-ops/src/ops/copy/copy-directory-transforms.test.ts ("multi-file skill directories" describe block) and apps/pair-cli/src/commands/install/handler.test.ts ("Skill corpus effectiveness: trigger descriptions, shared references, progressive disclosure, sharpened criteria, router fixes, authoring standard + eval #313 T5 prerequisite" describe block, full production-shaped pipeline).

What was disclosed, per orchestrator

Orchestrator	Disclosed	Sibling file	SKILL.md size
implement	Phase 4 (Post-Review Merge, Steps 4.1–4.4 + completion output) — only reached on the post-approval re-invocation branch, not the main task loop	post-review-merge.md	423 → 371 lines
review	Step 3.2's Level 1–4 adoption-compliance procedures — only the ONE level matching Step 3.1's determination ever applies on a given run	degradation-levels.md	391 → 285 lines
review	Phase 6 (Merge & Close, Steps 6.1–6.6 + completion output) — only reached when the reviewer picks "Merge now" in Step 5.4 (review's own description already calls this phase "optional")	merge-and-cascade.md	(same file, combined above)
bootstrap	Step 2.2's assess-* recommended sequence + section-ownership table + parallel-safety/partial-installation notes — only reached when at least one assess-* skill is installed	assess-orchestration.md	314 → 283 lines

Each disclosed block is replaced in SKILL.md with a sharp context pointer naming exactly what's there and when it applies (e.g. "see degradation-levels.md for the exact steps of each of the 4 levels"), per the authoring standard's principle 2. HALT conditions stay co-located in SKILL.md's main HALT list even where the detailed steps moved (e.g. implement's "PR not approved (Step 4.1)").

Verification (AC5 bar)

Install dry-run with fixture: see Prerequisite check above — confirmed failing pre-fix, passing post-fix, now a permanent regression test in both content-ops and pair-cli.

Orchestrator dry-run reaches disclosed material (installed mirror only, one scenario per orchestrator):

1. implement — scenario: developer re-invokes /pair-process-implement after PR approval. Mirror SKILL.md Phase 4 reads "...re-invoke /pair-process-implement to merge and close — see post-review-merge.md for the verify-approval, merge-commit, merge, and parent-cascade steps..."; post-review-merge.md contains Steps 4.1–4.4 and the merge completion output. Pointer resolves, material found.
2. review — scenario: Level 3 degradation (only /pair-capability-assess-stack installed). Mirror SKILL.md Step 3.2 reads "Run the procedure for the level determined in Step 3.1 — see degradation-levels.md..."; degradation-levels.md contains the Level 3 procedure. Pointer resolves, material found.
3. review (second scenario, Phase 6) — reviewer selects "Merge now" in Step 5.4. Mirror SKILL.md Phase 6 reads "...see merge-and-cascade.md for the merge-strategy, merge-commit, merge, parent-cascade, branch-cleanup, and post-merge-manual-test steps..."; sibling contains Steps 6.1–6.6. Pointer resolves, material found.
4. bootstrap — scenario: at least one assess-* skill installed. Mirror SKILL.md Step 2.2 reads "...see assess-orchestration.md for the sequence, each skill's owned adoption-file section, and the parallel-safety/partial-installation rules"; sibling contains the 8-item sequence and the 9-row section-ownership table. Pointer resolves, material found.

Mirror discipline

Dataset (packages/knowledge-hub/dataset/.skills/process/{implement,review,bootstrap}/) and .claude/skills/pair-process-{implement,review,bootstrap}/ updated in the same commit for all 7 touched/new files (3 edited SKILL.md + 4 new sibling files), byte-consistent under the existing flatten+prefix name-rewrite transform (/verify-quality → /pair-capability-verify-quality, etc.) — verified by regenerating the 3 skill dirs through the real (now-fixed) install pipeline and diffing against the committed mirrors; the only differences are the established slash-rewrite pattern plus this task's own edits. One regex boundary quirk in the automated pipeline (/record-decision( immediately followed by ( isn't matched by the boundary-aware rewrite regex — a pre-existing, narrow limitation, not part of this fix) was corrected by hand in the 2 new sibling files that contain that exact substring, matching the pattern already established in the pre-existing mirrors.

Testing

pnpm --filter @pair/knowledge-hub test         PASS — 6 files, 101 tests (incl. check:links: all markdown links valid)
pnpm skills:conformance                        PASS — 35 skills conformant (frontmatter portability, size limits, pointer resolution)
pnpm docs:staleness                            PASS — 35 skills, 8 commands in sync
pnpm mdlint:check                              PASS — 5/5 packages
pnpm --filter @pair/content-ops test           PASS — 49 files, 620 tests (incl. new multi-file-skill fixture test)
pnpm --filter @pair/content-ops lint           PASS
pnpm --filter @pair/content-ops ts:check       PASS
pnpm --filter @pair/pair-cli test              PASS — 71 files, 835 tests (incl. cli.e2e.test.ts and new #313 T5 prerequisite fixture test)
pnpm --filter @pair/pair-cli ts:check          PASS

Files Changed

• Modified (3 × 2 = 6): process/{implement,review,bootstrap}/SKILL.md (dataset + .claude/skills mirror) — disclosed sections replaced with context pointers.
• Added (4 × 2 = 8): post-review-merge.md (implement), degradation-levels.md + merge-and-cascade.md (review), assess-orchestration.md (bootstrap) — dataset + mirror.
• Fixed (1): packages/content-ops/src/ops/link-rewriter.ts — same-directory sibling link rebase (the CLI gap from the prerequisite check).
• Test-only (2): packages/content-ops/src/ops/copy/copy-directory-transforms.test.ts, apps/pair-cli/src/commands/install/handler.test.ts — permanent multi-file-skill fixture regression tests.

Refs: #313

---

🤖 Generated with Claude Code