brief
Interactive briefing of a plan file — explains reasoning, schema decisions, component choices. Use when developers need to understand a plan before approving.
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/brief
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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
$ARGUMENTShas a path, use itOtherwise, find latest plan:
Use Glob to find
.claude/plans/*/plan.mdand pick the most recent.If no plan found, tell user and suggest
/phx:planRead 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 ${CLAUDE_SKILL_DIR}/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: ", "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 ${CLAUDE_SKILL_DIR}/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:workwithout 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
${CLAUDE_SKILL_DIR}/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
Files (claude-elixir-phoenix)
-
references
-
briefing-guide.md 9.5 KB
Loading… -
visual-explainer.md 2.3 KB
Loading…
-
-
SKILL.md 4.7 KB
--- name: brief description: Interactive briefing of a plan file — explains reasoning, schema decisions, component choices. Use when developers need to understand a plan before approving. effort: low argument-hint: "[path to plan file]" --- # 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 1. If `$ARGUMENTS` has a path, use it 2. Otherwise, find latest plan: Use Glob to find `.claude/plans/*/plan.md` and pick the most recent. 3. If no plan found, tell user and suggest `/phx:plan` 4. 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 `${CLAUDE_SKILL_DIR}/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 `${CLAUDE_SKILL_DIR}/references/briefing-guide.md` for section content templates. ## Iron Laws 1. **ONE section at a time** — never dump all content 2. **User controls pace** — always offer to stop 3. **Explain WHY, not just WHAT** — rationale over listing 4. **Ground in artifacts** — focus on insights specific to this plan's research, decisions, and scratchpad entries, not general programming concepts 5. **Keep each section under 20 lines** — this is a briefing, not a lecture 6. **NEVER skip sections or auto-start work** — briefing is read-only; do not execute plan tasks or launch `/phx:work` without explicit user request 7. **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 ```text /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 `${CLAUDE_SKILL_DIR}/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
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.