升级Trellis并精简项目知识（09-05-trellis-upgrade-rule-cleanup）
更新Trellis适配、任务归属与归档失败恢复，精简技能入口和知识读取规则。 保留权限、证据、事务及独立复核合同；纳入对应任务及已完成复核记录。 仅本地提交，不启用新平台适配，不推送或部署。
这个提交包含在：
@@ -1,200 +1,21 @@
|
||||
---
|
||||
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."
|
||||
description: "Resolve unclear requirements and consequential design choices before implementation; produce or update the owning Trellis plan."
|
||||
---
|
||||
|
||||
# Trellis Brainstorm
|
||||
# Plan The Requested Change
|
||||
|
||||
## Non-Negotiable Planning Contract
|
||||
Use the project's workflow and task contract. Reuse a suitable task; create one only when needed and authorized. Task creation alone is not implementation approval. Keep unrelated tasks and historical evidence intact.
|
||||
|
||||
A request to build, implement, fix, refactor, or "go ahead" is not approval to leave planning. Task-creation consent is also not implementation approval.
|
||||
Inspect relevant code, tests and fact sources before asking questions. Separate observed behavior from intended behavior: existing code is evidence, not authority to redefine the user's goal. Search past dialogue only when a necessary decision is missing from current context and task records.
|
||||
|
||||
For non-trivial work, present the plan and obtain approval before implementation. Approval of the same plan in prior turns remains valid; clerical backfill, unchanged artifacts or repeated planning breadcrumbs do not restart the approval gate. Once decisions and required artifacts are complete, start and execute the approved scope.
|
||||
Resolve routine implementation choices within the user's authorized scope. Ask about consequential product, compatibility, UX, risk or acceptance decisions that remain unclear; state the recommendation and trade-off. A blocking answer is required before dependent work, while independent evidence gathering may continue. Do not invent questions or treat silence as approval.
|
||||
|
||||
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`.
|
||||
Record the smallest plan that makes the work reviewable:
|
||||
- `prd.md`: goal, relevant facts, scope/exclusions, observable acceptance, test plan and unresolved decisions.
|
||||
- Complex work also needs `design.md` for contracts, trade-offs and rollout/rollback, plus `implement.md` for ordered work and checks. Lightweight tasks may be PRD-only.
|
||||
- Context manifests contain stable spec/research only. Sub-agent mode requires curated real entries; empty/legacy seed-only manifests do not qualify. Inline mode reads context directly and permits empty manifests.
|
||||
|
||||
## Non-Negotiable Evidence Rule
|
||||
Before requesting a new plan's approval, resolve blocking questions and consolidate temporary notes into the owning sections. Preserve requirement IDs, evidence anchors, decisions and acceptance mappings; do not rewrite an already clear PRD merely to satisfy a template. Defer technical unknowns explicitly only when doing so does not silently change required behavior.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.
|
||||
|
||||
## Preconditions
|
||||
|
||||
Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.
|
||||
|
||||
If no task exists yet, create one:
|
||||
|
||||
```bash
|
||||
TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --description "<one-line summary>" --slug <slug>)
|
||||
```
|
||||
|
||||
Use a concise title from the user's request. Both the title and `--description` must be non-empty — `create` rejects blanks, and a record with either one empty is refused at archive. Use a slug without a date prefix. `task.py create` adds the `MM-DD-` directory prefix automatically.
|
||||
|
||||
`task.py create` creates the default `prd.md`. Update that file with the current understanding before asking follow-up questions.
|
||||
|
||||
## Planning Flow
|
||||
|
||||
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. If this plan has not yet been approved, present its final summary and wait. If the same scope has already been approved, do not ask again.
|
||||
9. With recorded approval and complete artifacts, run `task.py start` and implement. Repeat review only for a material scope, risk or acceptance change.
|
||||
|
||||
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.
|
||||
|
||||
## Question Rules
|
||||
|
||||
Ask only one question per message.
|
||||
|
||||
Each question must include:
|
||||
|
||||
- the decision needed
|
||||
- why the answer matters
|
||||
- your recommended answer
|
||||
- the trade-off if the user chooses differently
|
||||
|
||||
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.
|
||||
|
||||
Recommendations are not default selections. Never choose a recommended product decision on the user's behalf merely because the user asked for implementation.
|
||||
|
||||
Do not manufacture clarification questions. Present a new plan for approval when needed; if the same plan is already approved and artifacts are complete, start implementation.
|
||||
|
||||
Final review is required for a new or materially changed plan, not for reformatting an already approved plan. Task-creation consent alone is not implementation approval.
|
||||
|
||||
## Thinking Framework: First Principles Analysis
|
||||
|
||||
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.
|
||||
|
||||
### Step 1: Restate the Problem
|
||||
|
||||
Strip away implementation details to one sentence.
|
||||
|
||||
> Bad: "We need to add Redis caching to the user profile endpoint"
|
||||
> Good: "User profile data takes too long to load"
|
||||
|
||||
### Step 2: List Fundamental Truths
|
||||
|
||||
What is absolutely true (not opinion or convention)?
|
||||
|
||||
| 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
|
||||
|
||||
For each component of the current plan:
|
||||
|
||||
- **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.
|
||||
|
||||
### Step 4: Build Up from Truths
|
||||
|
||||
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?"
|
||||
|
||||
### Step 5: Validate
|
||||
|
||||
- Does the solution solve the original problem?
|
||||
- What assumptions need verification?
|
||||
- What's the simplest experiment to test this?
|
||||
|
||||
## Requirement Convergence Gate
|
||||
|
||||
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
|
||||
|
||||
Lightweight tasks may omit `design.md` and `implement.md`; they may not skip evidence inspection, requirement convergence, final review, or fresh implementation approval.
|
||||
|
||||
The final planning summary must show Goal, In Scope, Out of Scope, Acceptance Criteria, Key Decisions, relevant Risks or Deferred Items, and artifact status.
|
||||
|
||||
## Artifact Rules
|
||||
|
||||
`prd.md` records requirements and acceptance:
|
||||
|
||||
- goal and user value
|
||||
- confirmed facts
|
||||
- requirements
|
||||
- acceptance criteria
|
||||
- out of scope
|
||||
- open questions that still block planning
|
||||
|
||||
`design.md` records technical design for complex tasks:
|
||||
|
||||
- architecture and boundaries
|
||||
- data flow and contracts
|
||||
- compatibility and migration notes
|
||||
- important trade-offs
|
||||
- operational or rollback considerations
|
||||
|
||||
`implement.md` records execution planning for complex tasks:
|
||||
|
||||
- ordered implementation checklist
|
||||
- validation commands
|
||||
- risky files or rollback points
|
||||
- follow-up checks before `task.py start`
|
||||
|
||||
Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`.
|
||||
|
||||
`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`; an empty manifest, or one holding only a legacy `_example` placeholder row, does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `trellis-before-dev`.
|
||||
|
||||
## PRD Convergence Pass
|
||||
|
||||
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.
|
||||
|
||||
The pass must be lossless:
|
||||
|
||||
- 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.
|
||||
|
||||
After the pass, read `prd.md` top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Before declaring planning ready:
|
||||
|
||||
- `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.
|
||||
- The user explicitly approved this scope for implementation; unchanged restatements and clerical backfill do not invalidate that approval.
|
||||
|
||||
Do not start implementation merely because the user originally asked for implementation.
|
||||
Present a concise plan with material risks and completion criteria. A recorded approval or explicit delegation covering this scope remains valid; clerical updates do not restart approval. Once required artifacts and decisions are complete, run the official `task.py start` command and continue approved implementation and checks. Reconfirm only material scope, risk or acceptance changes and separately protected operations.
|
||||
|
||||
在新工单中引用
屏蔽一个用户