Phx Brief

Plan Briefing

Interactive walkthrough of a plan's reasoning, decisions, and solution

shape. Designed for developers who need to understand a plan in 1-2

minutes instead of reading the full document.

Why This Exists

Plans answer "what to do" but bury "why." This skill bridges that

gap with an interactive walkthrough.

Usage

phx-brief                                    # Latest plan
phx-brief .claude/plans/user-auth/plan.md    # Specific plan

Arguments

• $ARGUMENTS = Path to plan file (optional, auto-detects latest)

Mode Detection

Read the plan file and determine mode from phase statuses:

• All phases [PENDING] = Pre-work briefing (what WILL happen)
• Any phase [COMPLETED] or [IN_PROGRESS] = Post-work briefing

(what WAS done and why)

Execution Flow

Step 1: Locate and Load Plan

• If $ARGUMENTS has a path, use it
• Otherwise, find latest plan:

Use Glob to find .claude/plans/*/plan.md and pick the most recent.

• If no plan found, tell user and suggest phx-plan
• Read the plan file

Step 2: Load Supporting Artifacts

Read what's available (don't fail if missing):

• .claude/plans/{slug}/summaries/consolidated.md (research summary)
• .claude/plans/{slug}/scratchpad.md (decisions, dead-ends)
• .claude/plans/{slug}/progress.md (work log, post-work only)

Step 3: Present Briefing Sections

Present ONE section at a time, wrapped in the visual briefing block

(see references/briefing-guide.md Visual Formatting).

**The section MUST be emitted as visible response text BEFORE the

AskUserQuestion call.** Content composed only in thinking/reasoning

is invisible to the user, and the question field is too short to

carry it. If the user would see only a "Continue?" dialog, the section

was never shown. Write the ★ Briefing block as normal output first,

then ask:

• If sections remain: question "Continue the briefing?" with options

"Next: {title}", "Ask me a question about this", "Stop here"

• If final section: no question needed, show closing message

Section Flow (Pre-Work Mode)

| # | Title | Source |

|---|-------|--------|

| 1 | What We're Building | Summary + Scope |

| 2 | Key Decisions | Technical Decisions + scratchpad rationale |

| 3 | Solution Shape | Phases overview + Data Model |

| 4 | Risks & Confidence | Risks table + unknowns/spikes |

Section Flow (Post-Work Mode)

| # | Title | Source |

|---|-------|--------|

| 1 | What Was Built | Summary + completion status |

| 2 | Key Decisions & Why | Technical Decisions + scratchpad |

| 3 | How It Was Built | Phases with implementation notes |

| 4 | Lessons & Patterns | Risks encountered + patterns used |

See references/briefing-guide.md for section content templates.

Iron Laws

• ONE section at a time — never dump all content
• User controls pace — always offer to stop
• Explain WHY, not just WHAT — rationale over listing
• Ground in artifacts — focus on insights specific to this

plan's research, decisions, and scratchpad entries, not general

programming concepts

• Keep each section under 20 lines — this is a briefing,

not a lecture

• NEVER skip sections or auto-start work — briefing is read-only; do not execute plan tasks or launch phx-work without explicit user request
• SECTION TEXT BEFORE THE QUESTION — every ★ Briefing block is

visible response text emitted before its AskUserQuestion; never

deliver a section only inside thinking or the question field

Closing Message

After final section (or when user stops):

That's the briefing! For full details, see:
{plan_path}

Ready to proceed? Try `phx-work {plan_path}` to start execution.

Post-work variant:

That's what was built! For full details, see:
{plan_path}

Consider `phx-compound` to capture key learnings for future reference.

Integration

phx-plan  -->  phx-brief (optional)  -->  phx-work  -->  phx-brief (optional)
  create       understand before            execute        understand after

Complex Plan Enhancement

For plans with 5+ phases or 4+ key decisions, consider suggesting

visual rendering after Section 3. See

references/visual-explainer.md for thresholds and commands.

Notes

• Runs in main conversation context (not a subagent)
• Model: no special requirement — uses default session model
• No artifacts written — briefing is ephemeral, plan IS the artifact
• Reference file readable since skill runs in user's session