docs(skills): constrain needs-design + require epic label on parent Epics

[thejustinwalsh]

Summary

Three skill-level tightenings against failure modes Epic #190 exposed in today's dogfood run.

Failure 1: silent Epic exclusion

I filed Epic #190 with labels phase:11,enhancement,dogfood and forgot epic. The recommender's listOpenEpics (packages/dispatcher/src/github.ts) discriminates by the epic label. Without it, #190 dropped out of the queue entirely — not in Ready, Needs human input, Blocked, or even Excluded. It just vanished. ~90 minutes lost diagnosing "queue is stuck" before I noticed the label diff in the epics cache.

• creating-github-issues Phase 6 now states the epic label is required on parent Epics.
• creating-github-issues red flags gain a "forgot the epic label" entry naming the silent-disappearance failure.
• recommending-github-issues gains an explicit instruction to surface "issue qualifies as an Epic by all other rules but is missing epic label" in ## Excluded with an actionable reason. Silent exclusion is the actual bug.

Failure 2: needs-design as a safety blanket

The agent that shipped PR #198 (file-backed Epic store) filed follow-up #200 with needs-design despite all three gaps in the body carrying concrete implementation paths — file names, function names, data shapes, verbs. None were design forks; they were enhancements waiting on a worktree A/B. The needs-design label is the most expensive in middle's vocabulary (auto-dispatch skips it until a maintainer un-labels), and the agent used it as a "want human ack first" escape hatch — the corporate trap.

• creating-github-issues red flags + implementing-github-issues red flags both gain an explicit constraint: needs-design requires ≥2 specific candidate approaches AND a stated reason why building each as a worktree-A/B POC wouldn't decide. "Feels designy" / "want human ack first" / "more work than I want to handle in this PR" are explicitly rejected as rationales. Default is build to disambiguate.

I stripped needs-design from #200 today; the recommender will pick it up next tick.

Failure 3: complexity pause without an enumerated candidate list

The complexity-pause section (under "Running under middle") had the right structural rule — A/B/C up to complexity_ceiling, pause above it — but no enforcement against feelings of complexity. Agents have been pausing without writing down the candidates. Hardened to require the literal exercise of writing the fork list before any kind=complexity pause. The body now reads:

Mandatory before raising a complexity pause: write the candidate list. In blocked.json's context, list every fork by name with a one-sentence concrete approach (file paths + verbs, not vibes). If you can't articulate ≥ complexity_ceiling + 1 concrete forks this way, it isn't a complexity pause — you're rationalizing an easy choice as hard. […] Most "complexity pauses" don't survive contact with the list.

Three honest outcomes follow from the list: 1 fork = pick it; 2–3 forks = Architectural-forks worktree mechanic; ≥ complexity_ceiling + 1 distinct concrete approaches with no clear winner = real pause. The list is the gate.

Plus a matching red-flag entry: "This feels like a complexity pause → feelings aren't forks."

Verification

• bun run typecheck — clean
• bun run sync-skills — bootstrap-assets mirror re-synced
• bun test packages/cli/test/state-issue-body.test.ts packages/dispatcher/test/state-issue.test.ts — 19 pass

Summary by CodeRabbit

• Documentation
  • Parent issue guidance: parent issues must include the epic label to appear in recommendation queues.
  • Clarified needs-design: only for cases with multiple concrete, named implementation candidates where forks won’t resolve the choice.
  • Complexity pause: require an explicit, named candidate-fork list before pausing and specify outcomes (pick obvious winner, use forks for 2–3, pause only for many unresolved approaches).
  • Recommendation workflow: explicitly surface excluded epics missing the epic label with corrective instructions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 006a7c1c-2fd8-4490-8be5-651c30ab4b8d

📥 Commits

Reviewing files that changed from the base of the PR and between 947aa47 and 4950422.

📒 Files selected for processing (2)

• packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md
• packages/skills/implementing-github-issues/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md
• packages/skills/implementing-github-issues/SKILL.md

---

📝 Walkthrough

Walkthrough

Documentation updates to GitHub issue creation, implementation, and recommendation workflows establish stricter label discipline: the epic label is required on all parent issues and must be surfaced if missing; needs-design is limited to genuine architectural fork-and-POC scenarios and complexity pauses require concrete fork lists.

Changes

Label Requirements and Workflow Rules

Layer / File(s)	Summary
Epic label requirement and recommender visibility packages/cli/src/bootstrap-assets/skills/creating-github-issues/SKILL.md, packages/skills/creating-github-issues/SKILL.md, packages/cli/src/bootstrap-assets/skills/recommending-github-issues/SKILL.md, packages/skills/recommending-github-issues/SKILL.md	Parent issue filing instructions mandate the epic label for every parent, with updated examples showing the label in use. The recommender must surface Epics missing this label in the ## Excluded section with a concrete gh issue edit <n> --add-label epic instruction.
Needs-design label usage and complexity-pause preconditions packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md, packages/skills/implementing-github-issues/SKILL.md	needs-design is restricted to the rare case of multiple concrete candidate implementations that require fork-and-POC evaluation. Complexity pauses now require writing a named, concrete candidate-forks list (with file paths and verbs) to .middle/blocked.json; the document defines when to proceed, when to use architectural forks, and when to legitimately pause.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• thejustinwalsh/middle#89: Edits the base creating-github-issues skill content; related to the epic/labeling guidance updated here.

Suggested labels

ready-for-review

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main changes: constraining needs-design usage and requiring the epic label on parent Epics, which are the core objectives of the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md`:
- Around line 715-730: The fenced code block that contains the three "Fork ..."
bullet lines (starting with "Fork A: stringify the slug into the existing
numeric `epicNumber`...") is missing a language identifier; update that
triple-backtick fence to include a language (e.g., ```text or ```md) so the
block is properly rendered and accessible in SKILL.md, keeping the block
contents unchanged.

In `@packages/skills/implementing-github-issues/SKILL.md`:
- Around line 715-730: The fenced code block in the `blocked.json` example
inside the `context` section is missing a language identifier; update that
fenced block (the one starting with the line containing "Fork A: stringify the
slug into the existing numeric `epicNumber`...") to include an appropriate
language tag (e.g., text or md) after the opening triple backticks so the block
renders correctly and improves accessibility.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8cf2cb08-59ac-4f51-8c58-24cd5b50f00a

📥 Commits

Reviewing files that changed from the base of the PR and between 03256cb and 947aa47.

📒 Files selected for processing (6)

• packages/cli/src/bootstrap-assets/skills/creating-github-issues/SKILL.md
• packages/cli/src/bootstrap-assets/skills/implementing-github-issues/SKILL.md
• packages/cli/src/bootstrap-assets/skills/recommending-github-issues/SKILL.md
• packages/skills/creating-github-issues/SKILL.md
• packages/skills/implementing-github-issues/SKILL.md
• packages/skills/recommending-github-issues/SKILL.md

✅ Files skipped from review due to trivial changes (3)

• packages/cli/src/bootstrap-assets/skills/recommending-github-issues/SKILL.md
• packages/skills/recommending-github-issues/SKILL.md
• packages/cli/src/bootstrap-assets/skills/creating-github-issues/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/skills/creating-github-issues/SKILL.md