升级 Trellis 并完成项目审查（07-26-trellis-upgrade-project-audit）
这个提交包含在：
@@ -3,546 +3,198 @@ name: trellis-brainstorm
|
||||
description: "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."
|
||||
---
|
||||
|
||||
# Brainstorm - Requirements Discovery (AI Coding Enhanced)
|
||||
# Trellis Brainstorm
|
||||
|
||||
**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.
|
||||
## Non-Negotiable Planning Contract
|
||||
|
||||
Ask the questions one at a time.
|
||||
A request to build, implement, fix, refactor, or "go ahead" is not approval to leave planning. Task-creation consent is also not implementation approval.
|
||||
|
||||
For every non-trivial task, the user must respond at least once after the initial request before implementation begins. If no clarification is needed, that response must approve the final planning summary described below.
|
||||
|
||||
While any user-owned product, scope, UX, compatibility, risk, or acceptance decision remains unresolved, end the turn with exactly one highest-value question. Do not edit product code, dispatch implementation, or run `task.py start`.
|
||||
|
||||
## Non-Negotiable Evidence Rule
|
||||
|
||||
If a question can be answered by exploring the codebase, explore the codebase instead.
|
||||
|
||||
---
|
||||
This is mandatory. Before asking the user a question, first check whether the answer is already available in code, tests, configs, docs, existing specs, or task history.
|
||||
|
||||
Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
|
||||
Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, acceptance behavior, or decisions that remain ambiguous after inspection.
|
||||
|
||||
* **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)
|
||||
Repository evidence establishes current behavior and technical constraints. The user's intended behavior, feature scope boundaries, and UX preferences are never answerable by repository evidence alone, even when an existing pattern exists; existing patterns are options and recommendation evidence, not decisions.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
|
||||
|
||||
Triggered from `start` (Trellis command) when the user describes a development task, especially when:
|
||||
## Preconditions
|
||||
|
||||
* requirements are unclear or evolving
|
||||
* there are multiple valid implementation paths
|
||||
* trade-offs matter (UX, reliability, maintainability, cost, performance)
|
||||
* the user might not know the best options up front
|
||||
Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles (Non-negotiable)
|
||||
|
||||
1. **Task-first (capture early)**
|
||||
Always ensure a task exists at the start so the user's ideas are recorded immediately.
|
||||
|
||||
2. **Action before asking**
|
||||
If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
|
||||
|
||||
3. **One question per message**
|
||||
Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
|
||||
|
||||
4. **Prefer concrete options**
|
||||
For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
|
||||
|
||||
5. **Research-first for technical choices**
|
||||
If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
|
||||
|
||||
6. **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.
|
||||
|
||||
7. **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.
|
||||
If no task exists yet, create one:
|
||||
|
||||
```bash
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --slug <slug>)
|
||||
```
|
||||
|
||||
Use a slug without a date prefix. `task.py create` adds the `MM-DD-`
|
||||
directory prefix automatically.
|
||||
Use a concise title from the user's request. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
|
||||
|
||||
Create/seed `prd.md` immediately with what you know:
|
||||
`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
|
||||
|
||||
```markdown
|
||||
# brainstorm: <short goal>
|
||||
## Planning Flow
|
||||
|
||||
## Goal
|
||||
1. Capture the user's request and initial known facts in `prd.md`.
|
||||
2. Inspect available evidence before asking questions:
|
||||
- code, tests, fixtures, and configs
|
||||
- README files, docs, existing specs, and domain notes
|
||||
- related Trellis tasks, research files, and session history when present
|
||||
3. Separate what you found into:
|
||||
- confirmed facts
|
||||
- product intent still needed from the user
|
||||
- scope or risk decisions still needed from the user
|
||||
- likely out-of-scope items
|
||||
4. If a user-owned decision remains, ask the single highest-value question, include your recommendation and trade-off, then stop. Do not perform implementation work in the same turn.
|
||||
5. After each user answer, update `prd.md`, recompute the decision inventory, and repeat from step 2.
|
||||
6. When no user-owned decision remains, create or update `design.md` and `implement.md` for complex tasks.
|
||||
7. Run the requirement convergence gate, then the PRD convergence pass.
|
||||
8. Present the final planning summary and stop. Do not run `task.py start` or edit product code in the same turn.
|
||||
9. Only a subsequent user message that explicitly approves the latest planning summary authorizes `task.py start` and implementation. If the artifacts change materially after approval, repeat the final review.
|
||||
|
||||
<one paragraph: what + why>
|
||||
Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists.
|
||||
|
||||
## What I already know
|
||||
## Question Rules
|
||||
|
||||
* <facts from user message>
|
||||
* <facts discovered from repo/docs>
|
||||
Ask only one question per message.
|
||||
|
||||
## Assumptions (temporary)
|
||||
Each question must include:
|
||||
|
||||
* <assumptions to validate>
|
||||
- the decision needed
|
||||
- why the answer matters
|
||||
- your recommended answer
|
||||
- the trade-off if the user chooses differently
|
||||
|
||||
## Open Questions
|
||||
Do not ask process questions such as whether to search, inspect files, or continue brainstorming. Do the evidence work directly. Ask the user only when the remaining issue is a product decision, preference, scope boundary, or risk tolerance choice.
|
||||
|
||||
* <ONLY Blocking / Preference questions; keep list short>
|
||||
Recommendations are not default selections. Never choose a recommended product decision on the user's behalf merely because the user asked for implementation.
|
||||
|
||||
## Requirements (evolving)
|
||||
Do not manufacture clarification questions when the request and repository evidence already resolve every decision. In that case, proceed directly to the final planning summary, which still requires a subsequent explicit approval.
|
||||
|
||||
* <start with what is known>
|
||||
The final review is a required phase-transition gate, not a prohibited process question. Task-creation consent, the initial implementation request, and approval given before the latest final summary do not satisfy this gate.
|
||||
|
||||
## Acceptance Criteria (evolving)
|
||||
## Thinking Framework: First Principles Analysis
|
||||
|
||||
* [ ] <testable criterion>
|
||||
When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to fundamental truths before reasoning upward.
|
||||
|
||||
## Definition of Done (team quality bar)
|
||||
### Step 1: Restate the Problem
|
||||
|
||||
* Tests added/updated (unit/integration where appropriate)
|
||||
* Lint / typecheck / CI green
|
||||
* Docs/notes updated if behavior changes
|
||||
* Rollout/rollback considered if risky
|
||||
Strip away implementation details to one sentence.
|
||||
|
||||
## Out of Scope (explicit)
|
||||
> Bad: "We need to add Redis caching to the user profile endpoint"
|
||||
> Good: "User profile data takes too long to load"
|
||||
|
||||
* <what we will not do in this task>
|
||||
### Step 2: List Fundamental Truths
|
||||
|
||||
## Technical Notes
|
||||
What is absolutely true (not opinion or convention)?
|
||||
|
||||
* <files inspected, constraints, links, references>
|
||||
* <research notes summary if applicable>
|
||||
```
|
||||
| Category | Examples |
|
||||
|----------|----------|
|
||||
| **Physical constraints** | Network latency ≥ 0, disk I/O has limits |
|
||||
| **Business rules** | "Users must see their own data" |
|
||||
| **Technical invariants** | "Data must be consistent" |
|
||||
| **User needs** | "The user wants X within Y seconds" |
|
||||
|
||||
---
|
||||
### Step 3: Challenge Assumptions
|
||||
|
||||
## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)
|
||||
For each component of the current plan:
|
||||
|
||||
Before asking questions like "what does the code look like?", gather context yourself:
|
||||
- **Fact or convention?** "We always use REST" — why?
|
||||
- **What if we removed this?** If nothing breaks, it's unnecessary.
|
||||
- **Solving the actual problem or a symptom?** Trace the causal chain.
|
||||
- **Who benefits from this complexity?** If "nobody", simplify.
|
||||
|
||||
### Repo inspection checklist
|
||||
### Step 4: Build Up from Truths
|
||||
|
||||
* Identify likely modules/files impacted
|
||||
* Locate existing patterns (similar features, conventions, error handling style)
|
||||
* Check configs, scripts, existing command definitions
|
||||
* Note any constraints (runtime, dependency policy, build tooling)
|
||||
1. Start with the minimum viable mechanism satisfying all truths
|
||||
2. Add complexity only when a specific truth demands it
|
||||
3. Each addition must answer: "Which truth requires this?"
|
||||
|
||||
### Documentation checklist
|
||||
### Step 5: Validate
|
||||
|
||||
* Look for existing PRDs/specs/templates
|
||||
* Look for command usage examples, README, ADRs if any
|
||||
- Does the solution solve the original problem?
|
||||
- What assumptions need verification?
|
||||
- What's the simplest experiment to test this?
|
||||
|
||||
Write findings into PRD:
|
||||
## Requirement Convergence Gate
|
||||
|
||||
* Add to `What I already know`
|
||||
* Add constraints/links to `Technical Notes`
|
||||
Before final review, verify all of the following:
|
||||
|
||||
---
|
||||
- the user outcome and product value are explicit
|
||||
- in-scope and out-of-scope behavior are explicit
|
||||
- acceptance criteria describe observable outcomes
|
||||
- user-owned product, scope, UX, compatibility, and risk decisions are resolved
|
||||
- blocking open questions are empty
|
||||
- technical unknowns are researched or explicitly deferred without changing MVP behavior
|
||||
|
||||
## Step 2: Classify Complexity (still useful, not gating task creation)
|
||||
Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evidence inspection, requirement convergence, final review, or fresh implementation approval.
|
||||
|
||||
| Complexity | Criteria | Action |
|
||||
| ------------ | ------------------------------------------------------ | ------------------------------------------- |
|
||||
| **Trivial** | Single-line fix, typo, obvious change | Skip brainstorm, implement directly |
|
||||
| **Simple** | Clear goal, 1–2 files, scope well-defined | Ask 1 confirm question, then implement |
|
||||
| **Moderate** | Multiple files, some ambiguity | Light brainstorm (2–3 high-value questions) |
|
||||
| **Complex** | Vague goal, architectural choices, multiple approaches | Full brainstorm |
|
||||
The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
|
||||
|
||||
> Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
|
||||
## Artifact Rules
|
||||
|
||||
---
|
||||
`prd.md` records requirements and acceptance:
|
||||
|
||||
## Step 3: Question Gate (Ask ONLY high-value questions)
|
||||
- goal and user value
|
||||
- confirmed facts
|
||||
- requirements
|
||||
- acceptance criteria
|
||||
- out of scope
|
||||
- open questions that still block planning
|
||||
|
||||
Before asking ANY question, run the following gate:
|
||||
`design.md` records technical design for complex tasks:
|
||||
|
||||
### Gate A — Can I derive this without the user?
|
||||
- architecture and boundaries
|
||||
- data flow and contracts
|
||||
- compatibility and migration notes
|
||||
- important trade-offs
|
||||
- operational or rollback considerations
|
||||
|
||||
If answer is available via:
|
||||
`implement.md` records execution planning for complex tasks:
|
||||
|
||||
* repo inspection (code/config)
|
||||
* docs/specs/conventions
|
||||
* quick market/OSS research
|
||||
- ordered implementation checklist
|
||||
- validation commands
|
||||
- risky files or rollback points
|
||||
- follow-up checks before `task.py start`
|
||||
|
||||
→ **Do not ask.** Fetch it, summarize, update PRD.
|
||||
Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
|
||||
|
||||
### Gate B — Is this a meta/lazy question?
|
||||
`implement.md` is not a replacement for `implement.jsonl`. On sub-agent-dispatch workflows, `implement.jsonl` and `check.jsonl` must each contain at least one real spec/research entry before `task.py start`; the seed `_example` row does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `trellis-before-dev`.
|
||||
|
||||
Examples:
|
||||
## PRD Convergence Pass
|
||||
|
||||
* "Should I search?"
|
||||
* "Can you paste the code so I can proceed?"
|
||||
* "What does the code look like?" (when repo is available)
|
||||
Before declaring planning ready or running `task.py start`, rewrite `prd.md` once against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate.
|
||||
|
||||
→ **Do not ask.** Take action.
|
||||
The pass must be lossless:
|
||||
|
||||
### Gate C — What type of question is it?
|
||||
- Collapse repeated facts into one authoritative section.
|
||||
- Fold temporary brainstorm sections such as `What I already know`, `Assumptions`, and resolved `Open Questions` into Goal, Background, Requirements, Technical Notes, or Acceptance Criteria.
|
||||
- Remove resolved open questions instead of leaving empty or already-answered sections.
|
||||
- Merge parallel bug and requirement lists when they describe the same work; keep each defect's severity, evidence, and file:line anchors on the owning requirement.
|
||||
- Preserve every file:line anchor, decision, constraint, requirement ID, and acceptance-criteria mapping.
|
||||
- Do not proceed to final review while any blocking open question remains.
|
||||
|
||||
* **Blocking**: cannot proceed without user input
|
||||
* **Preference**: multiple valid choices, depends on product/UX/risk preference
|
||||
* **Derivable**: should be answered by inspection/research
|
||||
After the pass, read `prd.md` top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
|
||||
|
||||
→ Only ask **Blocking** or **Preference**.
|
||||
## Quality Bar
|
||||
|
||||
---
|
||||
Before declaring planning ready:
|
||||
|
||||
## Step 4: Research-first Mode (Mandatory for technical choices)
|
||||
- `prd.md` contains testable acceptance criteria.
|
||||
- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings.
|
||||
- Repository-answerable questions have already been answered through inspection.
|
||||
- Blocking open questions are empty.
|
||||
- Complex tasks have `design.md` and `implement.md`.
|
||||
- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready.
|
||||
- The latest final planning summary has been presented to the user.
|
||||
- In a subsequent message, the user explicitly approved that summary for implementation.
|
||||
|
||||
### 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.
|
||||
|
||||
Agent type: `trellis-research`
|
||||
Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
|
||||
|
||||
❌ Bad (what you must NOT do):
|
||||
```
|
||||
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:
|
||||
|
||||
1. Identify 2–4 comparable tools/patterns for its topic
|
||||
2. Summarize common conventions and why they exist
|
||||
3. Map conventions onto our repo constraints
|
||||
4. 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:
|
||||
|
||||
```markdown
|
||||
## Research References
|
||||
|
||||
* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
|
||||
* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
|
||||
|
||||
## 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)
|
||||
|
||||
1. **Future evolution**
|
||||
|
||||
* What might this feature become in 1–3 months?
|
||||
* What extension points are worth preserving now?
|
||||
|
||||
2. **Related scenarios**
|
||||
|
||||
* What adjacent commands/flows should remain consistent with this?
|
||||
* Are there parity expectations (create vs update, import vs export, etc.)?
|
||||
|
||||
3. **Failure & edge cases**
|
||||
|
||||
* Conflicts, offline/network failure, retries, idempotency, compatibility, rollback
|
||||
* Input validation, security boundaries, permission checks
|
||||
|
||||
### Expansion message template (to user)
|
||||
|
||||
```markdown
|
||||
I understand you want to implement: <current goal>.
|
||||
|
||||
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
|
||||
* Clarify `Out of Scope`
|
||||
|
||||
### Question priority (recommended)
|
||||
|
||||
1. **MVP scope boundary** (what is included/excluded)
|
||||
2. **Preference decisions** (after presenting concrete options)
|
||||
3. **Failure/edge behavior** (only for MVP-critical paths)
|
||||
4. **Success metrics & Acceptance Criteria** (what proves it works)
|
||||
|
||||
### Preferred question format (multiple choice)
|
||||
|
||||
```markdown
|
||||
For <topic>, which approach do you prefer?
|
||||
|
||||
1. **Option A** — <what it means + trade-off>
|
||||
2. **Option B** — <what it means + trade-off>
|
||||
3. **Option C** — <what it means + 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):
|
||||
|
||||
```markdown
|
||||
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:
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
|
||||
```markdown
|
||||
Here's my understanding of the complete requirements:
|
||||
|
||||
**Goal**: <one sentence>
|
||||
|
||||
**Requirements**:
|
||||
|
||||
* ...
|
||||
* ...
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
* [ ] ...
|
||||
* [ ] ...
|
||||
|
||||
**Definition of Done**:
|
||||
|
||||
* ...
|
||||
|
||||
**Out of Scope**:
|
||||
|
||||
* ...
|
||||
|
||||
**Technical Approach**:
|
||||
<brief summary + key decisions>
|
||||
|
||||
**Implementation Plan (small PRs)**:
|
||||
|
||||
* PR1: <scaffolding + tests + minimal plumbing>
|
||||
* PR2: <core behavior>
|
||||
* PR3: <edge cases + 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:
|
||||
|
||||
```bash
|
||||
# Create child tasks
|
||||
CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
|
||||
CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
|
||||
|
||||
# Or link existing tasks
|
||||
python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PRD Target Structure (final)
|
||||
|
||||
`prd.md` should converge to:
|
||||
|
||||
```markdown
|
||||
# <Task Title>
|
||||
|
||||
## Goal
|
||||
|
||||
<why + what>
|
||||
|
||||
## Requirements
|
||||
|
||||
* ...
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
* [ ] ...
|
||||
|
||||
## Definition of Done
|
||||
|
||||
* ...
|
||||
|
||||
## Technical Approach
|
||||
|
||||
<key design + decisions>
|
||||
|
||||
## Decision (ADR-lite)
|
||||
|
||||
Context / Decision / Consequences
|
||||
|
||||
## Out of Scope
|
||||
|
||||
* ...
|
||||
|
||||
## Technical Notes
|
||||
|
||||
<constraints, references, files, research notes>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns (Hard Avoid)
|
||||
|
||||
* Asking user for code/context that can be derived from repo
|
||||
* Asking user to choose an approach before presenting concrete options
|
||||
* Meta questions about whether to research
|
||||
* Staying narrowly on the initial request without considering evolution/edges
|
||||
* Letting brainstorming drift without updating PRD
|
||||
|
||||
---
|
||||
|
||||
## Integration with Start Workflow
|
||||
|
||||
After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**:
|
||||
|
||||
```text
|
||||
Brainstorm
|
||||
Step 0: Create task directory + seed PRD
|
||||
Step 1–7: Discover requirements, research, converge
|
||||
Step 8: Final confirmation → user approves
|
||||
↓
|
||||
Task Workflow Phase 2 (Prepare for Implementation)
|
||||
Code-Spec Depth Check (if applicable)
|
||||
→ Research codebase (based on confirmed PRD)
|
||||
→ Configure code-spec context (jsonl files)
|
||||
→ Activate task
|
||||
↓
|
||||
Task Workflow Phase 3 (Execute)
|
||||
Implement → Check → Complete
|
||||
```
|
||||
|
||||
The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
|
||||
|
||||
---
|
||||
|
||||
## Related Commands
|
||||
|
||||
| Command | When to Use |
|
||||
|---------|-------------|
|
||||
| ``start` (Trellis command)` | Entry point that triggers brainstorm |
|
||||
| ``finish-work` (Trellis command)` | After implementation is complete |
|
||||
| ``update-spec` (Trellis command)` | If new patterns emerge during work |
|
||||
Do not start implementation merely because the user originally asked for implementation.
|
||||
|
||||
在新工单中引用
屏蔽一个用户