OpenParable
Skip to content
← Back to skills

Auditing Epic Alignment

Productivity
auditing-epic-alignment

Auditing Epic Alignment is an Agent Skill for productivity published in the RackulaLives/Rackula repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RackulaLives/Rackula/blob/HEAD/.claude/skills/auditing-epic-alignment/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/auditing-epic-alignment, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

DriftHow to detectFix
Stale checkboxchild state != body checkboxcorrect the body
Misfiled issuechild milestone != epic'srelocate or re-note
False blockerclaimed dep already met at the artifact levelremove the dep, document why
Unmapped claimchecklist item with no linked issueflag; link, downgrade, or delete
Text-only parentingsub_issues returns emptywire native links
Phantom phasework with no issue and no near-term ownerdemote to one gated note; do not pre-create issues
Conflated scopeone epic, two audiences or data modelssplit 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 scopeSkill
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.