Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, asks high-value questions one at a time, researches technical choices, and converges on MVP scope. Use when requirements are unclear, there are multiple valid approaches, or the user describes a new feature or complex task.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, asks high-value questions one at a time, researches technical choices, and converges on MVP scope. Use when requirements are unclear, there are multiple valid approaches, or the user describes a new feature or complex task.
CoreRule: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
Ask the questions one at a time.
If a question can be answered by exploring the codebase, explore the codebase instead.
Guide AI through collaborative requirements discovery before implementation, optimized for AI coding workflows:
Task-first (capture ideas immediately)
Action-before-asking (reduce low-value questions)
Research-first for technical choices (avoid asking users to invent options)
Diverge → Converge (expand thinking, then lock MVP)
When to Use
Triggered from /trellis:start when the user describes a development task, especially when:
Task-first (capture early)
Always ensure a task exists at the start so the user's ideas are recorded immediately.
Action before asking
If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
One question per message
Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
Prefer concrete options
For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
Research-first for technical choices
If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
Diverge → Converge
After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.
No meta questions
Do not ask "should I search?" or "can you paste the code so I can continue?"
If you need information: search/inspect. If blocked: ask the minimal blocking question.
Step 0: Ensure Task Exists (ALWAYS)
Before any Q&A, ensure a task exists. If none exists, create one immediately.
Use a temporary working title derived from the user's message.
It's OK if the title is imperfect — refine later in PRD.
Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
Step 3: Question Gate (Ask ONLY high-value questions)
Before asking ANY question, run the following gate:
Gate A — Can I derive this without the user?
If answer is available via:
repo inspection (code/config)
docs/specs/conventions
quick market/OSS research
→ Do not ask. Fetch it, summarize, update PRD.
Gate B — Is this a meta/lazy question?
Examples:
"Should I search?"
"Can you paste the code so I can proceed?"
"What does the code look like?" (when repo is available)
→ Do not ask. Take action.
Gate C — What type of question is it?
Blocking: cannot proceed without user input
Preference: multiple valid choices, depends on product/UX/risk preference
Derivable: should be answered by inspection/research
→ Only ask Blocking or Preference.
Step 4: Research-first Mode (Mandatory for technical choices)
Trigger conditions (any → research-first)
The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
The user asks for "best practice", "how others do it", "recommendation"
The user can't reasonably enumerate options
Delegate to trellis-research sub-agent (don't research inline)
For each research topic, spawn a trellis-research sub-agent via the Task tool — don't do WebFetch / WebSearch / gh api inline in the main conversation.
Why:
The sub-agent has its own context window → doesn't pollute brainstorm context with raw tool output
It persists findings to {TASK_DIR}/research/<topic>.md (the contract — see workflow.md Phase 1.2)
It returns only {file path, one-line summary} to the main agent
Independent topics can be parallelized — spawn multiple sub-agents in one tool call
Codex exception: on Codex CLI, do NOT dispatch trellis-research for research-first mode — do the research inline (WebFetch / WebSearch in the main session) and write findings to {TASK_DIR}/research/<topic>.md yourself. Reason: Codex spawn_agent runs sub-agents with fork_turns="none" (isolated context, no parent session inheritance), so the research sub-agent cannot resolve the active task path via task.py current and silently aborts without producing files. Inline research on Codex avoids this failure mode. The 3+ inline research calls limit (B rule in workflow.md) is relaxed for Codex specifically.
Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
→ WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
→ Write(research/topic.md)
→ Pollutes main context with raw HTML/JSON, burns tokens.
✅ Good:
Main agent: Task(subagent_type="trellis-research",
prompt="Research topic A; persist to research/topic-a.md")
+ Task(subagent_type="trellis-research",
prompt="Research topic B; persist to research/topic-b.md")
+ Task(subagent_type="trellis-research",
prompt="Research topic C; persist to research/topic-c.md")
→ Reads research/topic-{a,b,c}.md after they finish.
Research steps (to pass into each sub-agent prompt)
Each trellis-research sub-agent should:
Identify 2–4 comparable tools/patterns for its topic
Summarize common conventions and why they exist
Map conventions onto our repo constraints
Write findings to {TASK_DIR}/research/<topic>.md
Main agent then reads the persisted files and produces 2–3 feasible approaches in PRD.
Research output format (PRD)
The PRD itself should only reference the persisted research files, not duplicate their content. Add a ## Research References section pointing at research/*.md.
Optionally, add a convergence section with feasible approaches derived from the research:
## Research References* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-linetakeaway>* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-linetakeaway>## Research Notes### What similar tools do* ...
* ...
### Constraints from our repo/project* ...
### Feasible approaches here**Approach A: <name>** (Recommended)
* How it works:
* Pros:
* Cons:
**Approach B: <name>*** How it works:
* Pros:
* Cons:
**Approach C: <name>** (optional)
* ...
Then ask one preference question:
"Which approach do you prefer: A / B / C (or other)?"
Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding
After you can summarize the goal, proactively broaden thinking before converging.
Expansion categories (keep to 1–2 bullets each)
Future evolution
What might this feature become in 1–3 months?
What extension points are worth preserving now?
Related scenarios
What adjacent commands/flows should remain consistent with this?
Are there parity expectations (create vs update, import vs export, etc.)?
I understand you want to implement: <currentgoal>.
Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
1. Future evolution: <1–2 bullets>
2. Related scenarios: <1–2 bullets>
3. Failure/edge cases: <1–2 bullets>
For this MVP, which would you like to include (or none)?
1. Current requirement only (minimal viable)
2. Add <X> (reserve for future extension)
3. Add <Y> (improve robustness/consistency)
4. Other: describe your preference
Then update PRD:
What's in MVP → Requirements
What's excluded → Out of Scope
Step 6: Q&A Loop (CONVERGE)
Rules
One question per message
Prefer multiple-choice when possible
After each user answer:
Update PRD immediately
Move answered items from Open Questions → Requirements
Update Acceptance Criteria with testable checkboxes
Failure/edge behavior (only for MVP-critical paths)
Success metrics & Acceptance Criteria (what proves it works)
Preferred question format (multiple choice)
For <topic>, which approach do you prefer?
1.**Option A** — <whatitmeans + trade-off>2.**Option B** — <whatitmeans + trade-off>3.**Option C** — <whatitmeans + trade-off>4.**Other** — describe your preference
Step 7: Propose Approaches + Record Decisions (Complex tasks)
After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
Based on current information, here are 2–3 feasible approaches:
**Approach A: <name>** (Recommended)
* How:
* Pros:
* Cons:
**Approach B: <name>*** How:
* Pros:
* Cons:
Which direction do you prefer?
Record the outcome in PRD as an ADR-lite section:
## Decision (ADR-lite)**Context**: Why this decision was needed
**Decision**: Which approach was chosen
**Consequences**: Trade-offs, risks, potential future improvements
Step 8: Final Confirmation + Implementation Plan
When open questions are resolved, confirm complete requirements with a structured summary:
Final confirmation format
Here's my understanding of the complete requirements:
**Goal**: <onesentence>**Requirements**:
* ...
* ...
**Acceptance Criteria**:
* [ ] ...
* [ ] ...
**Definition of Done**:
* ...
**Out of Scope**:
* ...
**Technical Approach**:
<briefsummary + keydecisions>**Implementation Plan (small PRs)**:
* PR1: <scaffolding + tests + minimalplumbing>* PR2: <corebehavior>* PR3: <edgecases + docs + cleanup>
Does this look correct? If yes, I'll proceed with implementation.
Subtask Decomposition (Complex Tasks)
For complex tasks with multiple independent work items, create subtasks:
