feat(writing-plans): conditional Flow Diagrams slot in the plan header template

[bannergz]

This PR targets the dev branch.

Who is submitting this PR? (required)

Field	Value
Your model + version	claude-opus-5 (Claude Opus 5)
Harness + version	Claude Code CLI 2.1.220 (Windows 11)
All plugins installed	superpowers 6.1.0, claude-mem 13.12.4, codspeed, private org plugins (yavendio-magic, vibegroup)
Human partner who reviewed this diff	Banner Gonzales (@bannergz) — reviewed the complete diff and PR body before submission

What problem are you trying to solve?

Real session, 2026-07-30. I used writing-plans to plan a feature spanning a Next.js dashboard, a FastAPI service, and a Rust webhook gateway — an onboarding flow where a signed webhook and a browser redirect race toward one idempotent completion. The plan came out structurally complete (header, file structure, per-task TDD steps, interfaces) but prose-only: the multi-actor flow lived in a 3-sentence Architecture paragraph. My human partner had to ask afterwards, explicitly, for a sequence diagram and a dataflow diagram — their words: it's "más entendible a nivel funcional para el developer" (easier to understand functionally for the developer reviewing/implementing the plan).

Baseline eval reproduces the failure deterministically: 3/3 fresh single-shot runs (claude-sonnet-5, no tools, condensed skill excerpt as system context, same spec shape) produced zero diagrams — no Mermaid, no ASCII, nothing — despite the spec being an inherently multi-actor async flow.

What does this PR change?

Adds a conditional ## Flow Diagrams slot to the Plan Document Header template, and a 4th Self-Review check that ties diagram arrow labels to the endpoints/events/functions the tasks implement. 12 added lines, one file (skills/writing-plans/SKILL.md).

Is this change appropriate for the core library?

Yes. It is domain-agnostic — any plan spanning 3+ components or an async boundary benefits, regardless of stack or project type. It adds no dependency: Mermaid fences render natively on GitHub and degrade to readable text elsewhere. Single-component plans are explicitly told to omit the section (conditional keyed on an observable predicate), so the slot does not bloat trivial plans.

The form follows the project's own doctrine (writing-skills → "Match the Form to the Failure"): the baseline failure is an omission of a required element, so the fix is a structural slot in the template the agent already fills in — not a prose reminder, not a prohibition.

What alternatives did you consider?

• Prose guidance in the Overview ("include diagrams for complex flows") — rejected: omission failures respond to REQUIRED slots in the template, not to reminders near it (per writing-skills).
• Unconditional requirement — rejected: a single-file/library plan would grow a scope-creep diagram. The conditional is keyed to an observable predicate (3+ interacting components, or any async boundary).
• A separate plan-reviewing skill — rejected as overkill for a 12-line structural gap; also overlaps existing open PRs in the review space (feat: add reviewing-plans skill — mandatory gate between writing-plans and executing-plans #1062, Add verifying-plan-coverage skill: prove a plan covers 100% of its spec before execution #1704) without addressing the authoring-time omission.

Does this PR contain multiple unrelated changes?

No. One file, one concern: the Flow Diagrams slot and its matching self-review check (the check is the enforcement half of the same slot).

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: none found addressing diagrams in plans (searched diagram, mermaid, sequence, writing-plans across open+closed). Same-shape precedents — template-slot additions to writing-plans: writing-plans: optional Invariants block for spec→test traceability #1831 (Invariants block), feat(writing-plans): add Evaluator section + self-review check #1627 (Evaluator section), feat(writing-plans): Global Constraints + per-task Interfaces as the two narrow exceptions to reference discipline (stacked on #1715) #1746 (Global Constraints + per-task Interfaces).

Environment tested

Harness	Harness version	Model	Model version/ID
Claude Code (Windows 11)	2.1.220	Claude Opus 5 (author/eval driver)	claude-opus-5
Claude Code subagents (eval reps)	2.1.220	Claude Sonnet 5	claude-sonnet-5

Eval evidence (before/after)

Method per writing-skills micro-testing: identical task + spec in both arms, condensed skill excerpt as the system context, one fresh single-shot subagent per rep, no tools, every output read manually. Spec: a 4-component merchant-onboarding flow (dashboard → API service → provider → webhook gateway) with a webhook/redirect completion race.

Arm	Reps	Plans with any diagram	Notes
Baseline (current SKILL.md)	3	0/3	Flow described only in the 3-sentence Architecture paragraph
With Flow Diagrams slot	3	3/3	Each produced a sequenceDiagram and a flowchart; all three independently modeled the webhook/redirect race with par/and; arrow labels matched task interfaces (finalize_connection(), POST /webhooks/kapso, verify_signature()); Self-Review check 4 was exercised and cited in all three outputs

Variance note: the with-slot arm converged on the same shape across reps (sequence + flowchart pair, labels from task interfaces), which per writing-skills is the signal that the wording binds.

🤖 Generated with Claude Code