---
satisfies: [R12, R31]
---

## Description

Rewrite the make-pr skill (heaviest single skill at 147 epic refs) to use spec vocabulary. Coordinates with T1's cognitive-aid payload top-level key rename (`epic` -> `spec`): every workflow.md reference to `epic.spec_sections.goal_and_context`, `epic.title`, `epic.acceptance_criteria` updates to `spec.spec_sections.*`, etc. CLI verb references update from `flowctl epic export-cognitive-aid` to `flowctl spec export-cognitive-aid`. Mermaid examples and prose narrative shift accordingly.

**Size:** M
**Files:**
- `plugins/flow-next/skills/flow-next-make-pr/SKILL.md`
- `plugins/flow-next/skills/flow-next-make-pr/workflow.md`
- `plugins/flow-next/skills/flow-next-make-pr/phases.md`
- `plugins/flow-next/skills/flow-next-make-pr/mermaid-rules.md`

## Approach

- Wholesale "epic" -> "spec" pass on prose throughout all 4 files. NOT a blind sed -- preserve places where "epic" is the right Agile-historical word (rare in this skill but possible in narrative paragraphs).
- Update CLI verb examples: `flowctl epic export-cognitive-aid <id> --base <ref> --json` -> `flowctl spec export-cognitive-aid <id> --base <ref> --json`.
- Update payload key references (R31): `epic.spec_sections.goal_and_context` -> `spec.spec_sections.goal_and_context`, `epic.title`, `epic.acceptance_criteria`, `epic.tasks`, etc. The payload structure is documented in workflow.md Phase 1 (gather inputs).
- Confirm hallucination guardrails (SKILL.md) still read correctly after rewrite.
- Mode-detection bash snippet near top of SKILL.md uses `EPIC_ID=` variable -- rename to `SPEC_ID=` for internal consistency. Argument parsing: positional argument is now "spec id", help text updates.
- mermaid-rules.md examples that reference epic IDs in node labels: update to use spec terminology consistently.

## Investigation targets

**Required:**
- `plugins/flow-next/skills/flow-next-make-pr/workflow.md` (~100 epic refs).
- `plugins/flow-next/skills/flow-next-make-pr/SKILL.md` (~14 refs).
- `plugins/flow-next/skills/flow-next-make-pr/phases.md` (~22 refs).
- `plugins/flow-next/skills/flow-next-make-pr/mermaid-rules.md` (~11 refs).

**Optional:**
- `plugins/flow-next/codex/skills/flow-next-make-pr/` -- regenerated by T15 from canonical; verify after. <!-- Updated by plan-sync: T6 done summary confirms Codex mirror regen lives in T15, not T13 -->

## Key context

- This skill is the most ref-dense single skill in the repo. Care with prose flow: the rewrite shifts pronoun usage (e.g., "the epic's R-IDs" -> "the spec's R-IDs") and section anchors.
- Coordinated with T1's payload key rename. T1 ships the JSON payload as `"spec":` top-level; this task makes the workflow prose match. If the two ship out of order, the skill emits broken jq paths; review-driven testing in T12 catches this.
- The dogfood test for this rewrite is running `/flow-next:make-pr fn-43-rename-epic-spec-across-flow-next` once the rename is complete (out of scope for this task; covered in spec-driven validation post-merge).

## Acceptance

- [ ] No `flowctl epic export-cognitive-aid` or `epic.spec_sections.*` or `epic.title` references in any of the 4 make-pr skill files.
- [ ] All payload key references match the post-T1 payload structure (top-level `"spec":` key).
- [ ] `EPIC_ID=` shell variable renamed to `SPEC_ID=` in SKILL.md mode-detection snippet.
- [ ] mermaid-rules.md examples consistent with spec vocabulary.
- [ ] Hallucination guardrails section in SKILL.md still readable + accurate post-rewrite.

## Done summary
Rewrote the make-pr skill (heaviest single skill at 147 epic refs across SKILL.md, workflow.md, phases.md, mermaid-rules.md) to use spec vocabulary: CLI verbs to `flowctl spec export-cognitive-aid`, payload keys to top-level `spec.*` (R31), bash variables `EPIC_ID` -> `SPEC_ID`, memory tag pattern `epic-<id>` -> `spec-<id>`, mermaid examples and prose narrative aligned. Branch-match resolution now scans both `.flow/specs/*.json` (post-1.0 canonical) and `.flow/epics/*.json` (legacy alias dir). Hallucination guardrails section reads cleanly post-rewrite; Codex review (gpt-5.5:high) confirmed R12 + R31 met with 0 introduced findings.
## Evidence
- Commits: 184cea363a1f7033dcc2213c415387942d6751b0
- Tests: bash plugins/flow-next/scripts/make-pr_smoke_test.sh (77/77 PASS)
- PRs: