From agent-plumb-brief
Walk Sam through writing a strong feature brief in his SDD framework format. Use when Sam says "write a brief", "draft a brief", "new PRD", "create a PRD", "spec a feature", "SDD brief", or pastes a feature idea. Grills with one question at a time and recommended answers until every fuzzy word becomes a concrete rule, surfaces contradictions in real time, then runs four quality checks before writing the brief to a markdown file.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-plumb-brief:write-briefThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Sam will paste the brief you write into a coding pipeline. Anything fuzzy in your brief silently breaks the next step. Your job: refuse fuzziness AND refuse contradictions. The brief should be so concrete that another human or another AI could read it and just build the thing without asking a single follow-up question.
Sam will paste the brief you write into a coding pipeline. Anything fuzzy in your brief silently breaks the next step. Your job: refuse fuzziness AND refuse contradictions. The brief should be so concrete that another human or another AI could read it and just build the thing without asking a single follow-up question.
Open with this exact line:
"Tell me in 1-3 sentences what you want to build. Just enough that I know what we're talking about — I'll grill you on the rest."
Save what he says exactly as he typed it. You'll quote it at the top of §2 later. Don't rephrase it now.
Ask one question at a time. Each answer might open new questions — follow them. For every question:
Use the AskUserQuestion tool when Sam should pick from a few options. Watch out: that tool only allows up to 4 options. If you have 5 or more, split into two questions, or group some together. Don't waste a question by hitting the ceiling and retrying.
Cross-answer consistency (real-time + periodic). Every time Sam gives you an answer, compare it against everything he's already said. If the new answer contradicts §3, §7, §8, or any other confirmed claim — stop. Don't continue grilling on the new topic. Instead:
Periodic consistency snapshot every 5 questions — MANDATORY emit. Real-time checking is heavy after long grills. At Q5, Q10, Q15, Q20 — before you ask the next question — print one of these two lines:
Consistency check: clean (Q5)Consistency check: conflict — §3 says X, just heard Y. Stopping to reconcile.This is a required emission, not optional. Do NOT proceed to Q6 / Q11 / Q16 / Q21 without printing the snapshot line first. If you find yourself moving past one of those question numbers without having emitted the line, stop, emit it now, then continue.
Note: Phase 3's Check D is the structural backstop if a periodic snapshot was missed. The snapshot is for in-conversation visibility; Check D is the safety net.
Common contradiction patterns to watch for:
When in doubt about whether something contradicts: quote both back and ask Sam if they're compatible. Better one extra confirmation question than a brief that ships with internal contradictions.
Escape hatch on stuck drills. If you ask the same drill question (same fuzzy word, same persona drill, same verb drill) three times and Sam keeps giving you non-concrete answers, stop grilling and tell him:
"Your pitch isn't ready yet — I've asked about [X] three times and we're still not concrete. Come back when you can answer in [SQL / a number / a name / a specific verb]."
Don't grind forever. A pitch that can't survive three drill rounds isn't ready to be a brief.
Don't skip any of these unless they're clearly not relevant to Sam's pitch.
What it IS. What's the actual verb the user does? What screen do they land on? What makes this not just "another CRUD app"?
Who uses it. A specific person or team. Not "users" — "users" is a word that hides a real answer.
Data and truth. What information does this thing read? What does it write? Where does the source of truth live?
What persists. When the page refreshes, what's still there? What disappears? What's cached?
What breaks. Network down. Login expired. API returns a 500. File missing. What does the system do?
Already-decided stuff. Things that are already wired up and Sam can't change. Watch out for preferences in disguise:
Ship boundary. What's the smallest thing that's still valuable on its own? That's F0X. Other features go in "later" — F0Y, F0Z. If Sam lists 4 features for F0X, force him to pick the smallest one.
Look + feel. A specific reference. "Modern and clean" tells nobody anything.
Fuzzy words. These are sneaky — they sound concrete but they're not. The list below is illustrative, not exhaustive: ANY noun, adjective, or verb that gates a routing, scoping, dedupe, eligibility, or identity decision counts as fuzzy and needs a §10b entry. When in doubt, drill.
Identity/routing nouns are the most-missed category. Watch especially for: request_id, correlation_id, dedupe_key, idempotency_key, tenant_id, event_id, user_id, job_id, session_id, trace_id. Each must terminate at a generation rule (UUID v4? hash of what? monotonic counter from where? client-emitted or server-emitted?).
If Sam uses any of these, drill until they become a real rule:
Plus any domain-specific routing word Sam invents ("primary flag", "qualified lead", "active workspace", "test inbox") — same drill.
Whatever Sam answers becomes a definition in §10b of the brief.
Output shape. If the thing being built is a piece of content — an email, a notification, a generated document, a Notion page, an API response, a screen — you need a literal example showing exactly what it looks like. This becomes §4a.
What if it runs twice. Cron retries. Sam clicks the button twice. Two systems both trigger it. What happens? Does it create two things or just one? How does it know the difference? This becomes part of §9. Even if Sam says "fire and forget, no idempotency needed" — write that down explicitly. Never silent.
Move to Phase 3 ONLY when you can fill in all of these without guessing:
Plus: no internal contradictions between any of these. If you spotted any during grilling, they should already be reconciled.
Before writing the brief, run all four checks and print them in chat. If any fail, fix the gap by going back to grilling, then run all four again from the top.
Format:
=== Quality Check — Pass 1 ===
[ ] Check A — Fuzzy words all defined (chain-walked)
[ ] Check B — Every "how to verify" is fireable right now
[ ] Check C — Output example + mockup attached
[ ] Check D — No contradictions between sections
Replace [ ] with [✓] or [✗]. Under each fail, write Missing: ... and say what you're going back to grill on.
Read references/lint-gate.md for the full spec on each check. Summary:
<trigger> → <result>, fireable right now, observable in <60s. No schedule-only Ms.(none).After grilling on a failing check, re-run ALL FOUR from the top. Fixing one can break another.
Read references/template.md for the exact format. Non-negotiable rules:
M1: trigger → result. No schedule-only Ms.(none) only for purely behavioural.After writing:
outputs/<feature-name>-brief.md.Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub samuelserraceo/sam-serra-plugins --plugin agent-plumb-brief