foomakers · rucka · Jul 14, 2026
diff --git a/.claude/skills/pair-process-bootstrap/SKILL.md b/.claude/skills/pair-process-bootstrap/SKILL.md
@@ -99,38 +99,7 @@ Orchestrate the complete project setup sequence. Transforms a PRD into a fully c
 ### Step 2.2: Assessment Phase (Optional)
 
 1. **Check**: Are assess-\* skills installed? Scan installed skills directory for `assess-*` skills.
-2. **Act** (installed): Compose assess-\* skills in recommended sequence. Each skill checks its own adoption file first — already-decided domains are skipped automatically (resolution cascade). **assess-\* skills are output-only**: each returns a proposal `{ content, target, decision-metadata }` and writes nothing. For each accepted proposal, `/pair-process-bootstrap` composes `/pair-capability-record-decision(content, target, decision-metadata)` — the **sole adoption writer** — to persist it. Never let an assess-\* skill write adoption directly.
-
-   **Recommended sequence** (respects adoption file dependencies):
-   1. `/pair-capability-assess-architecture` → proposes `architecture.md` content (needed by stack and infrastructure)
-   2. `/pair-capability-assess-stack` → proposes core sections of `tech-stack.md` (needed by testing and AI)
-   3. `/pair-capability-assess-testing` → proposes testing section of `tech-stack.md`
-   4. `/pair-capability-assess-ai` → proposes AI section of `tech-stack.md`
-   5. `/pair-capability-assess-infrastructure` → proposes `infrastructure.md` content (needed by observability)
-   6. `/pair-capability-assess-observability` → proposes observability section of `infrastructure.md`
-   7. `/pair-capability-assess-methodology` → proposes methodology section of `way-of-working.md`
-   8. `/pair-capability-assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/pair-capability-setup-pm` when installed)
-
-   After each assessment (or after collecting the batch), compose `/pair-capability-record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/pair-capability-assess-pm` persists via `/pair-capability-setup-pm` when that skill is installed; otherwise `/pair-process-bootstrap` persists its proposal via `/pair-capability-record-decision` like the others.
-
-   **Section ownership** (each assess-\* proposal owns its section; `/pair-capability-record-decision` preserves the rest on write):
-
-   | Adoption File        | Section            | Owner Skill            |
-   | -------------------- | ------------------ | ---------------------- |
-   | `architecture.md`    | Full file          | `/pair-capability-assess-architecture` |
-   | `tech-stack.md`      | Core sections      | `/pair-capability-assess-stack`        |
-   | `tech-stack.md`      | Testing section    | `/pair-capability-assess-testing`      |
-   | `tech-stack.md`      | AI section         | `/pair-capability-assess-ai`           |
-   | `infrastructure.md`  | Core sections      | `/pair-capability-assess-infrastructure` |
-   | `infrastructure.md`  | Observability      | `/pair-capability-assess-observability`|
-   | `way-of-working.md`  | Methodology        | `/pair-capability-assess-methodology`  |
-   | `way-of-working.md`  | PM tool            | `/pair-capability-assess-pm`           |
-   | `way-of-working.md`  | Quality gates      | `/pair-process-bootstrap` (Step 3.2)|
-
-   **Parallel safety**: Because assess-\* skills only produce proposals (no writes), they can run in parallel freely. The actual writes happen serially through `/pair-capability-record-decision` (the sole writer), which preserves sections it does not own. The recommended sequence orders the proposals by adoption-file dependency.
-
-   **Partial installation**: If only some assess-\* skills are installed, compose those and skip the rest with a warning. Each assess-\* skill is independent — partial installation is supported.
-
+2. **Act** (installed): Compose assess-\* skills in recommended sequence — see [assess-orchestration.md](assess-orchestration.md) for the sequence, each skill's owned adoption-file section, and the parallel-safety/partial-installation rules. Each skill checks its own adoption file first — already-decided domains are skipped automatically (resolution cascade). **assess-\* skills are output-only**: each returns a proposal `{ content, target, decision-metadata }` and writes nothing. For each accepted proposal, `/pair-process-bootstrap` composes `/pair-capability-record-decision(content, target, decision-metadata)` — the **sole adoption writer** — to persist it. Never let an assess-\* skill write adoption directly.
 3. **Act** (not installed): Warn and proceed with manual assessment:
 
    > assess-\* skills are not yet installed. Proceeding with manual assessment.

diff --git a/.claude/skills/pair-process-bootstrap/assess-orchestration.md b/.claude/skills/pair-process-bootstrap/assess-orchestration.md
@@ -0,0 +1,34 @@
+# Phase 2, Step 2.2: Assess-\* Orchestration — Detail
+
+Disclosed from [SKILL.md](SKILL.md) Step 2.2 — only reached when at least one `assess-*` skill is installed.
+
+**Recommended sequence** (respects adoption file dependencies):
+
+1. `/pair-capability-assess-architecture` → proposes `architecture.md` content (needed by stack and infrastructure)
+2. `/pair-capability-assess-stack` → proposes core sections of `tech-stack.md` (needed by testing and AI)
+3. `/pair-capability-assess-testing` → proposes testing section of `tech-stack.md`
+4. `/pair-capability-assess-ai` → proposes AI section of `tech-stack.md`
+5. `/pair-capability-assess-infrastructure` → proposes `infrastructure.md` content (needed by observability)
+6. `/pair-capability-assess-observability` → proposes observability section of `infrastructure.md`
+7. `/pair-capability-assess-methodology` → proposes methodology section of `way-of-working.md`
+8. `/pair-capability-assess-pm` → proposes PM section of `way-of-working.md` (delegates to `/pair-capability-setup-pm` when installed)
+
+After each assessment (or after collecting the batch), compose `/pair-capability-record-decision(content, target, decision-metadata)` to persist the proposal and record the ADR/ADL. `/pair-capability-assess-pm` persists via `/pair-capability-setup-pm` when that skill is installed; otherwise `/pair-process-bootstrap` persists its proposal via `/pair-capability-record-decision` like the others.
+
+**Section ownership** (each assess-\* proposal owns its section; `/pair-capability-record-decision` preserves the rest on write):
+
+| Adoption File        | Section            | Owner Skill            |
+| --------------------- | ------------------ | ---------------------- |
+| `architecture.md`    | Full file          | `/pair-capability-assess-architecture` |
+| `tech-stack.md`      | Core sections      | `/pair-capability-assess-stack`        |
+| `tech-stack.md`      | Testing section    | `/pair-capability-assess-testing`      |
+| `tech-stack.md`      | AI section         | `/pair-capability-assess-ai`           |
+| `infrastructure.md`  | Core sections      | `/pair-capability-assess-infrastructure` |
+| `infrastructure.md`  | Observability      | `/pair-capability-assess-observability`|
+| `way-of-working.md`  | Methodology        | `/pair-capability-assess-methodology`  |
+| `way-of-working.md`  | PM tool            | `/pair-capability-assess-pm`           |
+| `way-of-working.md`  | Quality gates      | `/pair-process-bootstrap` (Step 3.2)|
+
+**Parallel safety**: Because assess-\* skills only produce proposals (no writes), they can run in parallel freely. The actual writes happen serially through `/pair-capability-record-decision` (the sole writer), which preserves sections it does not own. The recommended sequence orders the proposals by adoption-file dependency.
+
+**Partial installation**: If only some assess-\* skills are installed, compose those and skip the rest with a warning. Each assess-\* skill is independent — partial installation is supported.
diff --git a/.claude/skills/pair-process-implement/SKILL.md b/.claude/skills/pair-process-implement/SKILL.md
@@ -307,48 +307,7 @@ Follow the TDD discipline rules strictly:
 
 ## Phase 4: Post-Review Merge
 
-After code review approval (typically via `/pair-process-review`), re-invoke `/pair-process-implement` to merge and close.
-
-### Step 4.1: Verify Review Approval
-
-1. **Check**: Is the PR approved by the reviewer?
-2. **Skip**: If not approved → **HALT**. Wait for review completion.
-3. **Verify**: PR has at least one approval.
-
-### Step 4.2: Prepare Merge Commit Message
-
-1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase).
-2. **Act**: Draft the final commit message:
-   - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md).
-   - **If merge or rebase**: use the default merge/rebase message.
-3. **Act** (BLOCKING): Present the commit message to the developer for confirmation:
-
-   > **Merge commit message:**
-   >
-   > ```text
-   > [#<story-id>] feat: <story description>
-   >
-   > - <summary of changes>
-   > - Tasks: T-1, T-2, ..., T-N
-   >
-   > Refs: #<story-id>
-   > ```
-   >
-   > Confirm or edit?
-
-4. **Verify**: Developer confirms the commit message.
-
-### Step 4.3: Merge PR
-
-1. **Act**: Merge the PR with the confirmed commit message and the configured merge strategy.
-2. **Verify**: PR merged and closed.
-
-### Step 4.4: Update Story & Parents
-
-1. **Act**: Update user story status to "Done" in the PM tool.
-2. **Act**: Check parent epic — if ALL stories in the epic are Done, update epic status to "Done".
-3. **Act**: Check parent initiative — if ALL epics in the initiative are Done, update initiative status to "Done".
-4. **Verify**: Story and parent hierarchy updated recursively.
+After code review approval (typically via `/pair-process-review`), re-invoke `/pair-process-implement` to merge and close — see [post-review-merge.md](post-review-merge.md) for the verify-approval, merge-commit, merge, and parent-cascade steps (Steps 4.1–4.4) plus the completion output.
 
 ## Output Format
 
@@ -365,17 +324,7 @@ IMPLEMENTATION COMPLETE:
 └── Quality:  [All gates passing]
 ```
 
-At merge (Phase 4):
-
-```text
-STORY DONE:
-├── Story:      [#ID: Title]
-├── PR:         [#PR-number — merged]
-├── Merge:      [squash | merge | rebase]
-├── Story:      Done
-├── Epic:       [#ID — Done | In Progress (X/Y stories done)]
-└── Initiative: [#ID — Done | In Progress (X/Y epics done)]
-```
+At merge (Phase 4): see [post-review-merge.md](post-review-merge.md).
 
 ## HALT Conditions
 

diff --git a/.claude/skills/pair-process-implement/post-review-merge.md b/.claude/skills/pair-process-implement/post-review-merge.md
@@ -0,0 +1,56 @@
+# Phase 4: Post-Review Merge — Detail
+
+Disclosed from [SKILL.md](SKILL.md) Phase 4 — only reached when `/pair-process-implement` is re-invoked after code review approval (typically via `/pair-process-review`), to merge and close the story.
+
+### Step 4.1: Verify Review Approval
+
+1. **Check**: Is the PR approved by the reviewer?
+2. **Skip**: If not approved → **HALT**. Wait for review completion.
+3. **Verify**: PR has at least one approval.
+
+### Step 4.2: Prepare Merge Commit Message
+
+1. **Check**: Read [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md) for merge strategy (squash, merge, rebase).
+2. **Act**: Draft the final commit message:
+   - **If squash**: combine all commits into a single message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md).
+   - **If merge or rebase**: use the default merge/rebase message.
+3. **Act** (BLOCKING): Present the commit message to the developer for confirmation:
+
+   > **Merge commit message:**
+   >
+   > ```text
+   > [#<story-id>] feat: <story description>
+   >
+   > - <summary of changes>
+   > - Tasks: T-1, T-2, ..., T-N
+   >
+   > Refs: #<story-id>
+   > ```
+   >
+   > Confirm or edit?
+
+4. **Verify**: Developer confirms the commit message.
+
+### Step 4.3: Merge PR
+
+1. **Act**: Merge the PR with the confirmed commit message and the configured merge strategy.
+2. **Verify**: PR merged and closed.
+
+### Step 4.4: Update Story & Parents
+
+1. **Act**: Update user story status to "Done" in the PM tool.
+2. **Act**: Check parent epic — if ALL stories in the epic are Done, update epic status to "Done".
+3. **Act**: Check parent initiative — if ALL epics in the initiative are Done, update initiative status to "Done".
+4. **Verify**: Story and parent hierarchy updated recursively.
+
+## Output Format (merge)
+
+```text
+STORY DONE:
+├── Story:      [#ID: Title]
+├── PR:         [#PR-number — merged]
+├── Merge:      [squash | merge | rebase]
+├── Story:      Done
+├── Epic:       [#ID — Done | In Progress (X/Y stories done)]
+└── Initiative: [#ID — Done | In Progress (X/Y epics done)]
+```
diff --git a/.claude/skills/pair-process-review/SKILL.md b/.claude/skills/pair-process-review/SKILL.md
@@ -142,36 +142,7 @@ This phase uses a **4-level graceful degradation cascade** depending on which op
 
 ### Step 3.2: Run Adoption Check
 
-**Level 1** (/pair-capability-verify-adoption + /pair-capability-assess-stack):
-
-1. Compose `/pair-capability-verify-adoption` with `$scope = all`.
-2. For each non-conformity:
-   - **Tech-stack**: compose `/pair-capability-assess-stack` (output-only — returns a proposal) → on developer approval, `/pair-process-review` persists the entry via `/pair-capability-record-decision(content, target)` (the sole writer); on rejection → CHANGES-REQUESTED.
-   - **Architecture**: report to developer for resolution. Missing ADR → HALT via `/pair-capability-record-decision`.
-   - **Other** (security, coding-standards, infrastructure): report findings.
-3. Record all results.
-
-**Level 2** (/pair-capability-verify-adoption only):
-
-1. Compose `/pair-capability-verify-adoption` with `$scope = all`.
-2. For tech-stack non-conformities: report as findings for manual resolution.
-3. For other non-conformities: same as Level 1.
-4. Record results.
-
-**Level 3** (/pair-capability-assess-stack only):
-
-1. Inline check: scan PR diff for new dependencies not in [tech-stack.md](../../../.pair/adoption/tech/tech-stack.md).
-2. For unlisted dependencies: compose `/pair-capability-assess-stack` (output-only — returns a proposal) → on approval, `/pair-process-review` persists via `/pair-capability-record-decision`; on rejection, flag as CHANGES-REQUESTED.
-3. No broader adoption compliance check (security, architecture, etc. — covered partially by Phase 2).
-4. Record results.
-
-**Level 4** (neither installed):
-
-1. Warn:
-
-   > `/pair-capability-verify-adoption` and `/pair-capability-assess-stack` are not installed — skipping automated adoption compliance. Please manually verify code against adoption files.
-
-2. Move to Phase 4.
+Run the procedure for the level determined in Step 3.1 — see [degradation-levels.md](degradation-levels.md) for the exact steps of each of the 4 levels.
 
 ### Step 3.3: Verify Adoption Results
 
@@ -246,77 +217,9 @@ Based on compiled findings:
 
 4. **Verify**: If "Merge now" selected → proceed to Phase 6. Otherwise → output and stop.
 
-## Phase 6: Merge & Close (APPROVED only)
-
-### Step 6.1: Read Merge Strategy
-
-1. **Check**: Is merge strategy specified in [way-of-working.md](../../../.pair/adoption/tech/way-of-working.md)?
-2. **Skip**: If not specified, default to `squash`.
-3. **Act**: Read the adopted merge strategy (`squash`, `merge`, or `rebase`).
-4. **Verify**: Strategy determined.
-
-### Step 6.2: Prepare Merge Commit
-
-1. **Act**: Draft the merge commit message following the [commit template](../../../.pair/knowledge/guidelines/collaboration/templates/commit-template.md):
-
-   ```text
-   [#<story-id>] feat: <story description>
-
-   - <summary of changes>
-   - Tasks: T-1, T-2, ..., T-N
+## Phase 6: Merge & Close (APPROVED only, optional)
 
-   Refs: #<story-id>
-   ```
-
-2. **Act** (BLOCKING): Present to reviewer for confirmation:
-
-   > **Merge commit message:**
-   >
-   > ```text
-   > [commit message]
-   > ```
-   >
-   > Confirm or edit?
-
-3. **Verify**: Reviewer confirms message.
-
-### Step 6.3: Merge PR
-
-1. **Act**: Merge the PR using the adopted strategy (per [github-implementation.md](../../../.pair/knowledge/guidelines/collaboration/project-management-tool/github-implementation.md)):
-   - MCP-first: use `merge_pull_request` with `merge_method` and `commit_title` + `commit_message`.
-   - CLI fallback: `gh pr merge <number> --squash --subject "<title>" --body "<body>"`.
-2. **Verify**: PR merged and closed.
-
-### Step 6.4: Update Story & Parent Cascade
-
-1. **Act**: Close the user story issue in the PM tool:
-   - MCP: `issue_write` with `method = update`, `state = closed`, `state_reason = completed`.
-   - CLI: `gh issue close <story-number> --reason completed`.
-2. **Act**: Check parent epic — read sub-issues to determine if ALL stories are Done:
-   - MCP: `issue_read` with `method = get_sub_issues` on the epic.
-   - If all sub-issues closed → close the epic with `state_reason = completed`.
-   - If not all closed → leave epic open.
-3. **Act**: Check parent initiative — same cascade logic:
-   - If all epics closed → close the initiative.
-   - If not all closed → leave initiative open.
-4. **Verify**: Story closed. Epic and initiative updated if applicable.
-
-### Step 6.5: Branch Cleanup
-
-1. **Act**: Delete the feature branch (remote):
-   - CLI: `git push origin --delete <branch>`.
-2. **Act**: Remove the story's checkpoint if one exists — `.pair/working/checkpoints/<story-id>.md` — so completed-story state does not linger as stale context (per the task-scoped cleanup rule; see `/pair-capability-checkpoint`).
-3. **Verify**: Feature branch deleted and story checkpoint removed (if any existed).
-
-### Step 6.6: Post-Merge Manual Test Validation (Optional)
-
-1. **Check**: Is `/pair-capability-execute-manual-tests` installed? Does the project have a manual test suite (`qa/` directory)?
-2. **Skip**: If skill not installed or no test suite found → skip. Log: "Manual test validation skipped — no suite or skill not installed."
-3. **Act**: Compose `/pair-capability-execute-manual-tests` with `$scope = all`, `$priority = P0` (blockers only for fast validation).
-4. **Verify**: If PASS → note in review output. If FAIL → do NOT revert the merge. Instead:
-   - Create a GitHub issue for each Critical/Major failure.
-   - Append manual test results as addendum to the review report (PR comment).
-   - Warn: "Post-merge manual tests found failures. Issues created."
+Only reached when the reviewer picked "Merge now" in Step 5.4 — see [merge-and-cascade.md](merge-and-cascade.md) for the merge-strategy, merge-commit, merge, parent-cascade, branch-cleanup, and post-merge-manual-test steps (Steps 6.1–6.6) plus the completion output.
 
 ## Output Format
 
@@ -335,18 +238,7 @@ REVIEW COMPLETE:
 └── Report:     [Posted as PR comment]
 ```
 
-At merge (Phase 6):
-
-```text
-STORY DONE:
-├── Story:        [#ID: Title]
-├── PR:           [#PR-number — merged]
-├── Merge:        [squash | merge | rebase]
-├── Story:        Done
-├── Epic:         [#ID — Done | In Progress (X/Y stories done)]
-├── Initiative:   [#ID — Done | In Progress (X/Y epics done)]
-└── Manual Tests: [PASS | FAIL — N issues created | SKIPPED — no suite]
-```
+At merge (Phase 6): see [merge-and-cascade.md](merge-and-cascade.md).
 
 ## HALT Conditions