⛔ This skill MUST be read in full — not skimmed. Formal review gates depend on its workflow.
Skipping steps silently bypasses quality checks. Missing gates = undetected breakages.

Human approval gate: presents output for user review. Pipeline advances after approval.
Verifier gate: dispatches AI reviewers. Pipeline auto-advances when clean.

Epic Workflow

Routes an epic through the full 6-stage fractal planning pipeline. Each stage invokes a Bounded sub-skill under planning/shared/. All review gates run at full depth.

Pipeline

Sub-skills live under ../planning/shared/. The shared routing stubs exist and dispatch to the underlying skills (e.g. shared/plan routes epics to epic-plan).

1. Align — shared/align/SKILL.md — Strategic go/no-go gate (full adversarial + Eisenhower)
2. Research — shared/research/SKILL.md — Research wrapper (full research brief)
3. Scope — shared/scope/SKILL.md — Scope + high-level E2E (all key functionality)
4. Plan — shared/plan/SKILL.md — 8 planning substeps with full review gates
5. Decompose — shared/decompose/SKILL.md — MECE-first + wiring + verification issues. Uses issue-creation skill for child issue generation.
6. Verify — shared/verify/SKILL.md — Pre + post-deploy verification

Hooks: Test-Design Gate fires between Scope and Plan; Capstone Verification Gate fires between Decompose and Verify. Both are mandatory stage hooks — see Gates below.

Reflect — session capture runs at session quit via reflect-hook.ts: writes a durable local JSONL record (~/.tortoise/session-events/) and POSTs to the hosted tortoise /v1/sessions endpoint only when hosted capture is explicitly opted in ("cloud": true in ~/.pi/agent/tortoise-config.json) AND a key is present (#803; a key alone never enables egress). A repo can opt out with <repo>/.pi/tortoise-capture.json {"cloud": false} or TORTOISE_CAPTURE_CLOUD=0. Cross-cutting: fires at epic completion, project close, and session quit.

Human Gates

Approval Routing (inlined from human-input-framework v2.1.1)

Canonical: skills/human-input-framework/SKILL.md → "Approval Routing — Canonical".
Inlined operational excerpt — cross-session resilience: this skill must run in a fresh session
without loading the framework skill first. Only the operational core is inlined; the status table,
store/transport contract, and Slack enablement live canonically (restating them is how the original
six copies drifted apart).

When a human gate fires, the agent MUST invoke the approval router to surface the request:

# Portable invocation (works from ANY repo checkout — swarm #1402 rollout):
python3 -c "
import os, sys
sys.path.insert(0, os.environ.get('SWARM_ROOT', os.path.expanduser('~/swarm')))
from operations.coordination.approval import request_approval
request_approval('product-strategist', artifact='<doc-name>.md', context='<stage> approval for epic <name>', requires_human=True)
print('Approval request created')
"

⛔ No dialog pops — do not wait for one. A pending request fires a macOS notification banner
(osascript … display notification), which has no buttons and no answer path; it is best-effort and
silently no-ops on non-macOS/CI/SSH. Reaching a human on Slack needs more than SLACK_BOT_TOKEN +
SLACK_APPROVAL_CHANNEL: the bridge derives a different store slug than the router, so
SLACK_APPROVAL_FILE must be pinned to the router's store (agent-infra #956) or the request just
waits in ~/.swarm/approvals/<slug>.json.

Detect the answer — read the record, never infer from a shrinking list:

SWARM="${SWARM_ROOT:-$HOME/swarm}/operations/coordination/approval.py"
python3 "$SWARM" --pending --role human    # still open
python3 "$SWARM" --status <req_id>         # this record's status + reviewer

A Slack thread reply sets changes_requested, which leaves --pending without approving;
is_approved(..., requires_human=True) also returns False after a Slack button approval (the
bridge overwrites reviewer with the clicking user's id — agent-infra #959). Trust status == 'approved'.

Role-based escalation: with APPROVAL_AUTO_APPROVE=0, omitting requires_human=True pends for
the requester's reports_to role — e.g. product-strategist for product-implementer; only
chain[1] is used, so nothing walks the chain further. Under the default (APPROVAL_AUTO_APPROVE
unset, which means 1) such a request auto-approves and never reaches a human — unless an
escalation keyword (deploy/delete/destroy/migrate/release) appears in the artifact/context,
which pends for a human regardless. Pass requires_human=True for a real human checkpoint.

1. After Scope — docs committed, GitHub URL presented
2. After Planning coherence — docs committed, GitHub URL presented

Decomposition gate is now an AI review gate (not human) — same review+fix loop pattern as other stages.

Gate Verification (between stages)

After completing each stage, before advancing to the next, the agent MUST verify the previous review gate was cleared.

Before Stage N:
  ☐ Previous stage output exists (doc committed, issue updated)
  ☐ Review gate result recorded (NO ISSUES FOUND or issues fixed + documented)
  ☐ If skipped: reason documented in plan doc
  ☐ If missing: GO BACK and complete the previous stage's review gate

⛔ HARD STOP: Do not proceed if the previous gate is incomplete.

This checkpoint runs at the start of every stage (2-6). The agent must explicitly confirm before stage execution begins.

UX Design Gate (between Scope and Plan)

After Scope approval (Human Gate #1) and before Plan (Stage 4): invoke ux-design-review skill when UX_RATING ≥ medium. This gate classifies UX decisions, presents structured options, and records user choices. It does NOT block — it surfaces and records.

ponytail: wired inline. shared/plan/SKILL.md exists — it routes epics to epic-plan and keeps project planning inline in project-workflow.

Test-Design Gate (between Scope and Plan)

Trigger: After Scope approval (Human Gate #1), before Plan (Stage 4). Fires alongside the UX Design Gate — both run before planning starts.

Action — Create test-design issue:

1. Dispatch the test-design skill to produce the epic's integration-surface map: every integration surface, the test layer assigned per surface (unit / pgTAP / contract / integration / e2e / ux), and failure modes per surface. Scope's Customer Value Map is the input — each scoped capability maps to at least one surface.
2. File the result as a child issue via issue-creation: test-design: <epic> integration-surface map (O/I/T, affiliation, complexity). The issue body must contain the FULL surface map so every downstream child issue can reference it.
3. Record the issue number in the epic plan doc.

Gate: Plan must NOT start until the test-design issue exists and its surface map covers every scoped capability. The map is the contract between scope and implementation — without it, child issues can't carry verification checklists (see epic-decompose).

Capstone Verification Gate (between Decompose and Verify)

Trigger: After Decompose (Stage 5) generates all child issues, before Verify (Stage 6) and before the epic can be marked complete.

Action — Create capstone verification issue:

1. Create one final child issue via issue-creation: capstone: clickthrough verification for <epic>.
2. The capstone is a final end-to-end clickthrough gate per the post-deploy-verify pattern: detect the deploy surface from the epic's PRs, walk the epic's high-level E2E test cases (from scope) as a real user, verify logs + database state, capture screenshots.
3. Its verification checklist = the epic's high-level E2E tests + the integration surfaces from the test-design map (each surface verified through its assigned test layer).

Gate: The capstone must PASS before the epic is marked complete — no epic completion without a passing capstone clickthrough. Its result feeds the Verify stage's Verification Proof; a failing or missing capstone blocks Verify from concluding.

Entity Mapping

Stage	Produces	Entity Class
Align	Align Decision	Decision (#17)
Research	Research Brief	ResearchBrief (#21)
Scope	Scope Brief + E2E Tests	Brief (#22)
Plan	Implementation Plan	Plan (#23)
Decompose	Child Issues + Wiring	Features (#15) + Tasks (#30)
Verify	Verification Proof	Proof (#24)
Reflect	ReflectDoc + FrictionEvents	Reflect (#50)

---

Continue following the workflow as mandated by this skill. Do not skip steps.