--- name: ultrabrief-local description: Interactive interview that produces a task brief with explicit research plan. Feeds /ultraresearch-local and /ultraplan-local. Optionally orchestrates the full pipeline end-to-end. argument-hint: "[--quick] " model: opus allowed-tools: Agent, Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion --- # Ultrabrief Local v2.1 Interactive requirements-gathering command. Produces a **task brief** — a structured markdown file that declares intent, goal, constraints, and an **explicit research plan** with copy-paste-ready `/ultraresearch-local` commands. Pipeline position: ``` /ultrabrief-local → brief.md (this command) /ultraresearch-local --project → research/*.md /ultraplan-local --project → plan.md /ultraexecute-local --project → execution ``` The brief is the contract between the user's intent and `/ultraplan-local`. Every decision the plan makes must trace back to content in the brief. **This command is always interactive.** There is no background mode — the interview requires user input. After the brief is written, the command optionally orchestrates the rest of the pipeline (research + plan) in foreground if the user opts in. ## Phase 1 — Parse mode and validate input Parse `$ARGUMENTS`: 1. If arguments start with `--quick`: set **mode = quick**. The interview starts more compactly (fewer opening probes per section) but still escalates automatically if quality gates fail. There is no hard cap on question count — quality drives the loop, not a counter. Strip the flag; remainder is the task description. 2. Otherwise: **mode = default**. Interview probes each section until the completeness gate (Phase 3) and brief-review gate (Phase 4) both pass. If no task description is provided, output usage and stop: ``` Usage: /ultrabrief-local /ultrabrief-local --quick Modes: default Dynamic interview until quality gates pass — brief with research plan --quick Compact start; still escalates on weak sections — brief with research plan Examples: /ultrabrief-local Add user authentication with JWT tokens /ultrabrief-local --quick Add rate limiting to the API /ultrabrief-local Migrate from Express to Fastify ``` Report: ``` Mode: {default | quick} Task: {task description} ``` ## Phase 2 — Generate slug and create project directory Generate a slug from the task description: first 3-4 meaningful words, lowercase, hyphens. Example: "Migrate from Express to Fastify" → `fastify-migration`. Set today's date as `YYYY-MM-DD` (UTC). Create the project directory: ```bash PROJECT_DIR=".claude/projects/{YYYY-MM-DD}-{slug}" mkdir -p "$PROJECT_DIR/research" ``` Report: ``` Project directory: .claude/projects/{YYYY-MM-DD}-{slug}/ ``` If the directory already exists and is non-empty, warn and ask: > "Directory {path} exists. Overwrite, reuse (keep existing files), or pick new slug?" Use `AskUserQuestion` with three options. If "pick new slug", ask for a new slug and restart Phase 2. ## Phase 3 — Completeness loop Phase 3 is a **section-driven completeness loop**. Instead of a numbered question list, maintain an internal state of brief sections and keep asking until every required section has substantive content. Quality drives the loop — there is no hard cap on question count. Use `AskUserQuestion` for every question. **Ask one question at a time.** Never dump multiple questions. ### Internal state Track this structure in memory as the loop runs: ``` state = { intent: { content: "", probes: 0 }, # required goal: { content: "", probes: 0 }, # required success_criteria: { content: [], probes: 0 }, # required research_plan: { topics: [], probes: 0 }, # required non_goals: { content: [], probes: 0 }, # optional constraints: { content: [], probes: 0 }, # optional preferences: { content: [], probes: 0 }, # optional nfrs: { content: [], probes: 0 }, # optional prior_attempts: { content: "", probes: 0 }, # optional question_history: [] # list of questions asked } ``` `content` is raw user answers merged; `probes` is how many times this section has been asked; `question_history` prevents re-asking the same variant twice. ### Required sections (initial-signal gate) Four sections MUST have substantive content before exiting Phase 3: 1. **Intent** — full sentence or paragraph (not a single word or phrase) 2. **Goal** — full sentence or paragraph 3. **Success Criteria** — at least one concrete, testable item 4. **Research Plan** — either ≥ 1 topic probed, OR the user has explicitly confirmed "no external research needed" "Substantive" means: non-empty, not a trivial one-word reply, not "I don't know" without a recorded assumption. The strict falsifiability check happens in Phase 4 (brief-review gate); Phase 3 is just the initial-signal bar. Optional sections (Non-Goals, Constraints, Preferences, NFRs, Prior Attempts) do not gate exit. If they remain empty after the required sections pass, they will be recorded as "Not discussed — no constraints assumed" in Phase 4's draft. ### Question bank (per section) Pick the next question from the section's bank based on `content` and `probes`. Wording must stay conversational — only the *selection* is section-driven, not the tone. **Intent** (required): - _Anchor_ (probes=0, content empty): "Why are we doing this? What is the motivation, the user need, or the strategic context behind the task?" - _Follow-up_ (probes≥1, content present but shallow): "What happens if we do nothing? Who is affected?" - _Sharpen_ (user mentioned a symptom): "You mentioned {X}. Is {X} the symptom or the underlying cause?" **Goal** (required): - _Anchor_: "Describe the end state in 1–3 sentences — specific enough to disagree with." - _Follow-up_: "How would you recognize this is done when looking at the UI / API / codebase?" **Success Criteria** (required): - _Anchor_: "How do we verify it is actually done? List 2–4 concrete, testable conditions — commands to run, observations, or metrics." - _Sharpen_ (criterion is vague): "'{quoted criterion}' is subjective. Which command, observation, or metric would prove this is met?" - _Quantify_ (performance/quality claim): "You mentioned it should be {fast/reliable/secure}. What number or threshold counts as success?" **Research Plan** (required, strictest): - _Anchor_ (no topics yet): "Are there technologies, libraries, or decisions in this task you do not have solid current knowledge of? Examples might be library choice, a protocol, or a security pattern." - _Per-topic sharpen_ (topic exists but incomplete): "For topic '{title}': which parts of the plan depend on the answer? What confidence level do you need — high, medium, or low?" - _Scope question_: "Is '{topic}' answerable from the existing codebase, from external docs, or both?" - _Confirm none_ (user refuses all topics): "Confirming: no external research needed — you already know everything the plan will depend on?" **Non-Goals** (optional): - _Anchor_: "What is explicitly NOT in scope? This prevents scope-guardian from flagging gaps for things we deliberately don't do." **Constraints** (optional): - _Anchor_: "Technical, time, or resource constraints the plan must respect? Dependencies, compatibility, deadlines, or budget." - _Sharpen_: "You mentioned {deadline / budget / compatibility}. Is it hard or guidance?" **Preferences** (optional): - _Anchor_: "Preferences for libraries, patterns, or architectural style?" **NFRs** (optional): - _Anchor_: "Performance, security, accessibility, or scalability targets? Quantified wherever possible." **Prior Attempts** (optional): - _Anchor_: "Has this been attempted before? What worked or failed?" ### Selection rule On each loop iteration: 1. Compute the next section to probe: - If any required section is below the initial-signal gate → pick the weakest required section in this priority order: Intent → Goal → Success Criteria → Research Plan. - Else if an optional section is clearly missing and likely material to scope (heuristic: the task description hints at constraints or NFRs) → probe it at most once. - Else: exit Phase 3. 2. Within the chosen section, pick the question variant: - If `probes == 0` and content is empty → _Anchor_. - If content exists but is shallow → _Follow-up_ or _Sharpen_. - If the section is Research Plan and topics exist → iterate per-topic sharpen across incomplete topics. 3. Ensure the exact question is NOT already in `question_history`. If it is, pick the next variant or skip to the next weakest section. 4. Ask via `AskUserQuestion`. Append question to history. Increment probes. 5. Record the answer into `content`. Never overwrite — merge. ### Research topic identification As the user answers Intent, Goal, or Success Criteria, listen for: - **Unfamiliar technologies** — libraries, frameworks, protocols not clearly present in the codebase - **Version upgrades** — migrating to a new major version - **Security-sensitive decisions** — auth, crypto, data handling - **Architectural choices** — pattern X vs Y, library A vs B - **Unknown integrations** — third-party APIs, external services - **Compliance / legal** — GDPR, accessibility, industry regulations When you hear one, add a *candidate* topic to `research_plan.topics` with only a title and why-it-matters. Probe it on the next Research Plan iteration using the per-topic sharpen question to fill in: - Research question (must end in `?`) - Required for plan steps - Scope (local / external / both) - Confidence needed (high / medium / low) - Estimated cost (quick / standard / deep) If the user says "I know this" to a candidate topic, remove it from the list. Trust the user. If no topics emerge after probing, the user confirms "no external research needed" → `research_plan` gate passes with 0 topics. ### Quick mode adjustments If **mode = quick**: - For optional sections, cap probes at 1 each. Do not revisit optional sections during Phase 3. - Required sections still have no probe cap — quality gate still applies. - Prefer _Anchor_ variants over _Sharpen_ on the first pass. ### Force-stop path If the user says "skip", "stop asking", "just proceed", "enough", or similar, break the loop immediately: - Mark any required sections still below the initial-signal gate as `{ incomplete_forced_stop: true }` in state. - Proceed to Phase 4 with a note that the brief will carry a reduced confidence flag. ### Exit condition Exit Phase 3 when: - All four required sections meet the initial-signal gate, OR - The user has force-stopped. Report: ``` Phase 3 complete: {N} questions asked across {M} sections. Proceeding to draft and review. ``` ## Phase 4 — Draft, review, and revise Phase 4 runs a **draft → brief-reviewer → revise** loop. The draft is not written to disk until the brief-review quality gate passes (or the iteration cap is hit). This ensures the brief that reaches `/ultraplan-local` has already survived a critical review. Read the brief template first: `@${CLAUDE_PLUGIN_ROOT}/templates/ultrabrief-template.md` ### Loop bound **Maximum 3 review iterations.** This bounds cost in the worst case while leaving room for two rounds of targeted follow-ups. ### Iteration step-by-step **Step 4a — Draft in memory** Build the brief text from Phase 3 state by filling the template: - **Frontmatter:** populate `task`, `slug`, `project_dir`, `research_topics` (count of topics), `research_status: pending`, `auto_research: false` (will update in Phase 5 if user opts in), `interview_turns` (total questions asked across Phase 3 + Phase 4), `source: interview`. - **Intent:** expand the user's motivation into 3–5 sentences. Load-bearing. - **Goal:** concrete end state. - **Non-Goals:** from state, or "- None explicitly stated" bullet if empty. - **Constraints / Preferences / NFRs:** from state, or "Not discussed — no constraints assumed" note if empty. - **Success Criteria:** falsifiable commands/observations from state. - **Research Plan:** one `### Topic N: {title}` section per topic with the full structure from the template. If 0 topics: write the "No external research needed — user confirmed solid knowledge of all plan dependencies" note. - **Open Questions / Assumptions:** from any `"I don't know"` answers recorded during Phase 3, plus implicit gaps. - **Prior Attempts:** from state, or "None — fresh task." **Step 4b — Write draft to disk** Write the draft to `{PROJECT_DIR}/brief.md.draft` (not `brief.md` — the final file is only written after the gate passes). **Step 4c — Launch brief-reviewer** Launch the `brief-reviewer` agent (foreground, blocking) with the prompt: > "Review this task brief for quality: `{PROJECT_DIR}/brief.md.draft`. > Check completeness, consistency, testability, scope clarity, and > research-plan validity. Report findings, verdict, and the required > machine-readable JSON block." **Step 4d — Parse JSON scores** Parse the agent's output. Locate the **last** fenced ```json``` block. Extract per-dimension scores: ``` review = { completeness: { score, gaps }, consistency: { score, issues }, testability: { score, weak_criteria }, scope_clarity: { score, unclear_sections }, research_plan: { score, invalid_topics }, verdict: "PROCEED | PROCEED_WITH_RISKS | REVISE" } ``` **JSON fallback:** if the JSON block is missing, invalid, or a dimension is missing, treat all dimensions as `score: 3` and set the `verdict` from the prose verdict if present, otherwise `PROCEED_WITH_RISKS`. Emit an internal note that the reviewer output was degraded. This ensures the loop never deadlocks on a parser error. **Step 4e — Gate evaluation** The gate **passes** when all of the following are true: - `completeness.score ≥ 4` - `consistency.score ≥ 4` - `testability.score ≥ 4` - `scope_clarity.score ≥ 4` - `research_plan.score == 5` (Research Plan requires a perfect score because its format is checked mechanically: ends in `?`, `Required for plan steps` filled, scope is one of `local | external | both`, confidence is `high | medium | low`. Anything less means at least one topic is malformed and planning will stumble.) **If gate passes:** 1. Move `brief.md.draft` → `brief.md` (atomic rename). 2. Delete the draft file if rename is not possible on the OS; write `brief.md` fresh. 3. Break the loop and proceed to Step 4g. **If gate fails AND iteration count < 3:** 1. Identify the weakest dimension (lowest score; tie broken by priority: research_plan > testability > completeness > consistency > scope_clarity). 2. Generate a targeted follow-up question from the dimension's detail field (gaps / issues / weak_criteria / unclear_sections / invalid_topics). Example generators: - `completeness.gaps: ["Non-Goals empty, unclear if deliberate"]` → "You did not specify anything out-of-scope. Is that deliberate, or are there things we should explicitly exclude?" - `testability.weak_criteria: ["'system should be fast'"]` → "'System should be fast' is not falsifiable. Which metric or threshold proves this is met — e.g., p95 < 200ms, or throughput ≥ X requests/sec?" - `research_plan.invalid_topics: [{"topic":"JWT","issue":"Required for plan steps empty"}]` → "For research topic 'JWT': which plan steps depend on the answer? Give one or two concrete kinds of step (e.g., 'library selection', 'threat model', 'migration strategy')." 3. Ask via `AskUserQuestion`. Record the answer into Phase 3 state. 4. Return to Step 4a with incremented iteration count. The reviewer sees an updated draft, so you MUST re-read the brief and regenerate the review each iteration — do not reuse stale scores. 5. When launching the reviewer on iteration 2 or 3, include prior questions in the prompt so it does not produce circular follow-ups: > "Questions already asked during this interview: {list from > question_history}. Focus on issues that remain after those answers — > do not re-raise gaps that have already been addressed." **If gate fails AND iteration count == 3 (loop exhausted):** 1. Move `brief.md.draft` → `brief.md`. 2. Add `brief_quality: partial` to the frontmatter (edit the file post-rename — insert the key above the closing `---`). 3. Add a `## Brief Quality` section near the end with the failing dimensions and their `detail` arrays from the final review, formatted: ``` ## Brief Quality Review loop exhausted after 3 iterations. The following dimensions did not reach the pass threshold: - **Research Plan (score 2/5):** Topic 'JWT library' missing Required-for-plan-steps field. - **Testability (score 3/5):** Success criterion "works correctly" is not falsifiable. Downstream planning will treat these as reduced-confidence areas. ``` 4. Break the loop and proceed to Step 4g. ### Step 4f — Force-stop handling If during any `AskUserQuestion` in Step 4e the user says "stop", "skip", "enough", "just write it", or similar, do NOT exit the loop immediately. Instead, surface the current review findings in plain text: ``` Brief-reviewer would flag these issues: - Research Plan (score 2/5): Topic 'JWT library choice' missing Required-for-plan-steps field. - Testability (score 3/5): Success criterion "works correctly" is not falsifiable. Continue anyway? The plan will have lower confidence in these areas. ``` Then ask via `AskUserQuestion`: | Option | Action | |--------|--------| | **Answer one more follow-up** | Return to Step 4e with the current weakest-dimension question. | | **Stop now (accept partial brief)** | Finalize brief with `brief_quality: partial` and the `## Brief Quality` section (same path as iteration-cap exhaustion). Break loop. | The force-stop path is distinct from a silent iteration cap: the user sees exactly which dimensions are weak and chooses informed. ### Step 4g — Finalize After the loop exits (pass, cap, or force-stop), ensure: - `brief.md` exists at `{PROJECT_DIR}/brief.md`. - `brief.md.draft` no longer exists. - If the loop ended without a clean pass, frontmatter contains `brief_quality: partial` and a `## Brief Quality` section exists. - If the loop ended with a clean pass, `brief_quality` is either absent or set to `complete`. Populate the "How to continue" footer with the actual project path and topic questions. **Schema sanity check (since v3.1.0):** before reporting, run the brief validator. This catches frontmatter typos and state-machine inconsistencies the brief-reviewer rubric does not check (e.g. `research_status: skipped` with `research_topics: 3` and no `brief_quality: partial`). ```bash node ${CLAUDE_PLUGIN_ROOT}/lib/validators/brief-validator.mjs --json "{PROJECT_DIR}/brief.md" ``` If the validator returns errors, report them to the user and offer to re-enter Phase 4 with the validator's hints in scope. If only warnings, note them in the final report. Report: ``` Brief written: {PROJECT_DIR}/brief.md Review iterations: {1..3} Final quality: {complete | partial} Validator: {PASS | warnings(N)} Research topics identified: {N} ``` ## Phase 5 — Auto-orchestration opt-in (if research_topics > 0) **Skip this phase if research_topics = 0.** Proceed directly to Phase 6. Ask the user via `AskUserQuestion`: **Question:** "You have {N} research topic(s). How do you want to proceed?" | Option | Description | |--------|-------------| | **Manual (default)** | Print the commands. You run `/ultraresearch-local` and `/ultraplan-local` yourself, choosing depth per topic. | | **Auto (managed by Claude Code)** | I run all {N} research topics sequentially in foreground, then automatically trigger `/ultraplan-local` when research completes. This session blocks until the plan is ready. | ### Manual path (default) Output: ``` ## Brief complete Project: {PROJECT_DIR}/ Brief: {PROJECT_DIR}/brief.md Research topics: {N} Next steps (run in order or parallel): {For each topic:} /ultraresearch-local --project {PROJECT_DIR} --external "{topic question}" Then: /ultraplan-local --project {PROJECT_DIR} Then: /ultraexecute-local --project {PROJECT_DIR} ``` Stop. Do not continue to Phase 6. ### Auto path Set `auto_research: true` in the brief's frontmatter (edit the file). Proceed to Phase 6. ## Phase 6 — Auto research dispatch (auto path only) **Runs only when user opted into auto mode.** ### Step 6a — Confirm proceed Tell the user auto mode will run in foreground and block the session, then confirm via `AskUserQuestion`: **Question:** "Auto mode runs {N} research topic(s) sequentially and then the plan — all in foreground. This session blocks until the plan is ready. Continue?" | Option | Action | |--------|--------| | **Continue — auto** | Proceed. | | **Cancel — do manual** | Revert to manual path (print commands, stop). | If cancelled → fall back to manual path output and stop. ### Step 6b — Run research topics sequentially (inline) Set `research_status: in_progress` in the brief's frontmatter. For each research topic (index i = 1 .. N), invoke `/ultraresearch-local` inline in this main-context session: ``` /ultraresearch-local --project {PROJECT_DIR} {--external | --local | (none)} "{topic i question}" ``` Pass the scope flag that matches the topic's scope hint. Wait for each invocation to finish writing the research brief at `{PROJECT_DIR}/research/{NN}-{topic-slug}.md` before moving to the next topic. > **Why sequential inline instead of parallel background?** Background > orchestrator-agents cannot spawn the research swarm — the Claude Code > harness does not expose the Agent tool to sub-agents, so a background > run silently degrades to single-context reasoning without WebSearch / > Tavily / WebFetch / Gemini (see v2.4.0 release notes). Running each > research pass inline in main context keeps the swarm intact. For true > parallel execution, use `claude -p` invocations in separate terminal > windows. ### Step 6c — Verify all briefs landed After the last topic completes, verify each research brief file exists: ```bash ls -1 {PROJECT_DIR}/research/*.md | wc -l ``` Expected count: N. If any are missing, report and ask the user how to proceed (retry, skip missing topic, cancel). Update brief frontmatter: `research_status: complete`. ### Step 6d — Auto-trigger planning (inline foreground) Invoke the planning command inline in this session: ``` /ultraplan-local --project {PROJECT_DIR} ``` The planning pipeline runs all phases (exploration, synthesis, review) in main context. Wait for the plan to be written to `{PROJECT_DIR}/plan.md` before continuing. ### Step 6e — Report completion When the planning-orchestrator finishes, present: ``` ## Ultrabrief + Ultraresearch + Ultraplan Complete (auto mode) **Project:** {PROJECT_DIR}/ **Brief:** {PROJECT_DIR}/brief.md **Research briefs:** {N} in {PROJECT_DIR}/research/ **Plan:** {PROJECT_DIR}/plan.md ### Pipeline summary | Step | Status | |------|--------| | Brief | Complete ({interview_turns} interview turns) | | Research | Complete ({N} topics, sequential foreground) | | Plan | Complete ({steps} steps, critic: {verdict}) | Next: /ultraexecute-local --project {PROJECT_DIR} Or: /ultraexecute-local --dry-run --project {PROJECT_DIR} # preview /ultraexecute-local --validate --project {PROJECT_DIR} # schema check ``` ## Phase 7 — Stats tracking Append one record to `${CLAUDE_PLUGIN_DATA}/ultrabrief-stats.jsonl`: ```json { "ts": "{ISO-8601}", "task": "{task description (first 100 chars)}", "slug": "{slug}", "mode": "{default | quick}", "interview_turns": {N}, "review_iterations": {1..3}, "brief_quality": "{complete | partial}", "research_topics": {N}, "auto_research": {true | false}, "auto_result": "{completed | cancelled | failed | manual}", "project_dir": "{path}" } ``` If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip silently. Never let stats failures block the workflow. ## Hard rules 1. **Interactive only.** This command requires user input. There is no `--fg` or background mode — the interview cannot run headless. 2. **Brief is the contract.** Every section must have substantive content or an explicit "Not discussed" note. No empty sections. 3. **Intent is load-bearing.** Do not accept a one-line intent. Expand with the user until motivation is clear — the plan and every review agent will trace decisions back to this. 4. **Research topics must be answerable.** Each topic's research question must be phrased so `/ultraresearch-local` can answer it. If a topic is too vague, split or reformulate before writing. 5. **Never invent research topics the user did not agree to.** Topics come from the interview. If the user says "I know this", respect it. 6. **Project dir is the single source of truth.** Every artifact (brief, research briefs, plan, progress) lives in one project directory. Never scatter files across `.claude/research/`, `.claude/plans/`, etc. 7. **Auto mode blocks foreground.** If the user opts into auto, this session waits for research + planning to complete. Document this in the opt-in question. 8. **Quality gates, not question counts.** Phase 3 and Phase 4 are quality-gated loops; do not enforce a hard cap on interview questions. The brief-review gate (Phase 4) caps at 3 review iterations to bound cost, but Phase 3 has no cap — required-section content drives exit. 9. **Never write `brief.md` while the review gate is still pending.** Draft lives in `brief.md.draft` until the loop terminates. A caller that sees `brief.md` must be able to trust that Phase 4 finished. 10. **Privacy:** never log prompt text, secrets, or credentials.