agentleFS
wayfarer35wayfarer35/ccs/.claude/skills/trellis-brainstorm/SKILL.md

trellis-brainstorm

Skill0 starsChanged 5 months agoMITView on GitHub

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.

20 other projects use a version of this, 13 of them edited; 12 of 13 edited versions we compared changed its rules; 1 new project in the last 4 weeks, against 0 the 4 before.

How people change it

12 of 13 edited versions changed its rules, and some changes recur.

Of the 13 edited versions we compared: 1 is an older text, 12 made changes of their own.

Not in older versions

  1. Before final review or task.py start, run the PRD convergence pass below.missing from 1 of 1
  2. 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.missing from 1 of 1
  3. What if we removed this? If nothing breaks, it's unnecessary.missing from 1 of 1
  4. Who benefits from this complexity? If "nobody", simplify.missing from 1 of 1
  5. Start with the minimum viable mechanism satisfying all truthsmissing from 1 of 1
  6. Add complexity only when a specific truth demands itmissing from 1 of 1
  7. 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.missing from 1 of 1
  8. Remove resolved open questions instead of leaving empty or already-answered sections.missing from 1 of 1

Rules people drop

  1. Ask the questions one at a time.dropped by 12 of 12
  2. Ask the single highest-value remaining question.dropped by 12 of 12
  3. After each user answer, update prd.md before continuing.dropped by 12 of 12
  4. Before final review or task.py start, run the PRD convergence pass below.dropped by 12 of 12
  5. Keep only genuinely blocking open questions.dropped by 12 of 12
  6. Do not start implementation until the user approves or asks for implementation.dropped by 12 of 12
  7. 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.dropped by 4 of 12

Rules people add

  1. A rule we can't quote: its licence doesn't allow itadded by 12 of 12
  2. A rule we can't quote: its licence doesn't allow itadded by 12 of 12
  3. A rule we can't quote: its licence doesn't allow itadded by 12 of 12
  4. A rule we can't quote: its licence doesn't allow itadded by 12 of 12
  5. A rule we can't quote: its licence doesn't allow itadded by 12 of 12
  6. A rule we can't quote: its licence doesn't allow itadded by 12 of 12
  7. A rule we can't quote: its licence doesn't allow itadded by 12 of 12
  8. A rule we can't quote: its licence doesn't allow itadded by 12 of 12

We split this file and each edited version into the rules they give an agent and match them by wording. A version that adds no rule of its own and has not changed since this file last did reads as an older text, so what it lacks is not counted as dropped. We keep no past texts of a file, so that is inferred, and an edited version that started from an older text still counts its gaps as drops.

Adopted by

Surging: 1 new project took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 1 new projectWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 1 in all, so this is a hint, not a trend.

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. 15 are common, 4 are distinctive, and 6 are very specific to this project.

  • 15

    Common

    Most of the 16 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ask the questions one at a time.

    line 12
  2. Common:

    If a question can be answered by exploring the codebase, explore the codebase instead.

    line 16
  3. Common:

    Do not ask the user to confirm facts that the repository can answer.

    line 20
  4. Common:

    Use this skill during Phase 1 planning to turn the user's request into clear requirements and planning artifacts.

    line 24
  5. Common:

    Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning.

    line 28
  6. Common:

    If no task exists yet, create one:

    line 30
  7. Very specific:

    Use a concise title from the user's request.

    line 36
  8. Distinctive:

    Ask the single highest-value remaining question.

    line 52
  9. Very specific:

    After each user answer, update prd.md before continuing.

    line 54
  10. Very specific:

    Before final review or task.py start, run the PRD convergence pass below.

    line 56
  11. Common:

    Do not invent a project-specific product/spec hierarchy.

    line 58
  12. Common:

    Ask only one question per message.

    line 62
  13. Common:

    Do not ask process questions such as whether to search, inspect files, or continue brainstorming.

    line 71
  14. Common:

    When requirements are vague, solutions feel over-engineered, or you're about to add complexity "because everyone does" — decompose to …

    line 75
  15. Common:

    What if we removed this?: If nothing breaks, it's unnecessary.

    line 100
  16. Common:

    Who benefits from this complexity?: If "nobody", simplify.

    line 102
  17. Common:

    Start with the minimum viable mechanism satisfying all truths

    line 106
  18. Common:

    Add complexity only when a specific truth demands it

    line 107
  19. Very specific:

    follow-up checks before task.py start

    line 140
  20. Very specific:

    Before declaring planning ready or running task.py start, rewrite prd.md once against the final structure described in the artifact rules …

    line 148
  21. Common:

    Remove resolved open questions instead of leaving empty or already-answered sections.

    line 154
  22. Distinctive:

    Keep only genuinely blocking open questions.

    line 157
  23. Very specific:

    After the pass, read prd.md top to bottom and verify that no fact is repeated across sections unless the repetition adds new information.

    line 159
  24. Common:

    Before declaring planning ready:

    line 163
  25. Distinctive:

    Do not start implementation until the user approves or asks for implementation.

    line 173

“Common” is measured: kept by at least 6 in 10 of the 16 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Trellis Brainstorm

Non-Negotiable Interview Contract

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.

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.

Do not ask the user to confirm facts that the repository can answer. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.


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:

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<short task title>" --slug <slug>)

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.

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. Ask the single highest-value remaining question.
  5. Include your recommended answer with the question.
  6. After each user answer, update prd.md before continuing.
  7. For complex tasks, create or update design.md and implement.md before implementation starts.
  8. Before final review or task.py start, run the PRD convergence pass below.

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.

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)?

CategoryExamples
Physical constraintsNetwork 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?

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; the seed _example 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.
  • Keep only genuinely blocking open questions.

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.
  • Remaining open questions are genuinely about user intent or scope.
  • 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 user has reviewed the final planning artifacts or explicitly approved proceeding.

Do not start implementation until the user approves or asks for implementation.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.