| name | phx-brief |
| description | Interactive briefing of a plan file — explains reasoning, schema decisions, component choices. Use when developers need to understand a plan before approving. |
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
