# Auditing Epic Alignment

> Use when an epic or milestone may have drifted from reality - checklist items that could be stale, issues possibly in the wrong milestone, a "gated on

- Skill: `rackulalives/auditing-epic-alignment` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rackulalives/auditing-epic-alignment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rackulalives/auditing-epic-alignment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rackulalives (https://skillmd.com/u/rackulalives)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rackulalives/auditing-epic-alignment

---


# Auditing Epic Alignment

Reference card. An epic body is a claim about reality, not reality itself; the longer it lives, the more its checklist, milestones, and "gated on #X" notes drift from actual issue states. Audit against live data, then split or re-scope.

The one subtle move: verify blockers at the ARTIFACT level, not the issue state. "Gated on #X" is not settled by #X being open or closed. Check the deliverable: is the PR merged to the default branch, does the file or schema already contain the change, are the docs live? Anything in draft or review does not unblock. (A year-old "blocked by #X" was once false because the schema file already carried the change and #X's generator was closed; that one check re-scoped a milestone.) A checklist item with no linked issue is an unverifiable claim, not a fact.

GitHub-specific (sub-issues API, milestones). For Jira/GitLab/Linear, adapt the live pull and skip native sub-issue wiring; the taxonomy still applies.

## Drift Types

| Drift | How to detect | Fix |
| --- | --- | --- |
| Stale checkbox | child state != body checkbox | correct the body |
| Misfiled issue | child milestone != epic's | relocate or re-note |
| False blocker | claimed dep already met at the artifact level | remove the dep, document why |
| Unmapped claim | checklist item with no linked issue | flag; link, downgrade, or delete |
| Text-only parenting | `sub_issues` returns empty | wire native links |
| Phantom phase | work with no issue and no near-term owner | demote to one gated note; do not pre-create issues |
| Conflated scope | one epic, two audiences or data models | split when independently deliverable; keep-with-cross-link when one is a subset or dependency of the other; close when superseded |

## Skill Routing

Load the matching skill to judge whether the epic's acceptance criteria and non-goals are complete and current. You are auditing alignment, not writing the work.

| Audited scope | Skill |
| --- | --- |
| auth, tokens, data ingress, serialization | /secure-coding |
| UI, components, accessibility | /frontend-design:frontend-design |
| splitting or re-phasing scope | /superpowers:brainstorming |
| before any tracker mutation | /superpowers:devils-advocate |
| audit unmasks untracked work | /gh-create |
| restructure spans many moves | /superpowers:writing-plans, then /orchestrate-issues |

## Execution (order matters)

1. Create or rename the destination (milestone, new epic) FIRST, so re-scope edits never reference a dangling target. Capture the new epic number.
2. Relocate children (`gh issue edit --milestone`).
3. Wire native sub-issues: `gh api -X POST repos/OWNER/REPO/issues/PARENT/sub_issues -F sub_issue_id=CHILD_ID`. `sub_issue_id` is the numeric database `.id` (`gh api .../issues/N -q .id`), NOT the issue number. The POST returns the parent, so a repeated parent id in the output is success. A child already parented elsewhere is rejected; resolve that first.
4. Edit the epic and parent bodies last, referencing the now-existing targets.
5. Repoint initiatives or siblings that named the moved work, then verify both trees (`.../sub_issues` and the milestone listing) before reporting done.
6. Present the changes as structured options and get approval before mutating. The human owns scope forks (which milestone, whether to split); offer tradeoffs, do not pre-decide them.

Maturity: reference card, intentionally light. Pressure-testing (see TESTING.md) found a capable model already verifies live and knows these mechanics, so this carries the non-obvious reference points and the routing, not a discipline apparatus.