Brd Research

brd-research — explore and document findings

you are doing research only. your job is to explore the problem space, document what you find, and present findings to the human. you do not propose a final design, write code, or close the issue.

this is a collaborative process. if you run into interesting findings, surprising constraints, or forks in the road as you explore, surface them to the human early — use AskUserQuestion (or your harness's equivalent) rather than stockpiling everything for the end.

1. pre-flight

brd show $ARGUMENTS --context

• confirm this is a type: design issue. if not, stop and tell the human.
• if not already claimed, claim it:

brd start $ARGUMENTS

2. exploration strategy

work through these steps in order. skip any that aren't relevant.

understand the problem:

• read the issue body carefully — what's being asked and why?
• read all dependency and dependent issues (brd show $ARGUMENTS --context already gave you these)
• identify the key constraints and success criteria

map the relevant code:

• use Glob to find files in the affected area
• use Grep to trace how existing functionality works
• use Read to understand the key modules, types, and interfaces
• note any relevant patterns the codebase already uses

check history:

• look at recent git log for the affected files — is there prior work, reverted attempts, or relevant context in commit messages?

identify approaches:

• come up with at least two viable approaches
• for each, note: what changes, what's easy, what's hard, what could go wrong

external research (when relevant):

• if the issue involves libraries, protocols, or patterns you're unsure about, use WebSearch/WebFetch
• look for prior art, known pitfalls, or best practices
• this step is optional — skip it for purely internal design questions

3. document findings

get the issue file path:

brd path $ARGUMENTS

edit the issue body to add a ## research findings section. use the structure from findings-template.md:

• context — what you explored and key observations
• options considered — at least two approaches with pros, cons, effort, and risk
• open questions — things you couldn't determine or that need human input
• recommendation — which option you lean toward and why (this is a suggestion, not a decision)

write findings directly into the issue file so they're preserved and visible to anyone who runs brd show.

4. present to human

after documenting findings, summarize them in your response:

• state what the issue is asking for (one sentence)
• list the options you found (brief)
• highlight the key trade-off or open question
• state your recommendation

then stop and wait for feedback. the human may:

• ask clarifying questions
• point you toward something you missed
• approve moving to design phase
• change direction entirely

5. anti-patterns

• don't write code. not even "rough sketches." research is read-only exploration.
• don't close the issue. research is not completion.
• don't create implementation issues. that's the design phase's job.
• don't skip documenting in the issue body. your chat messages disappear; the issue body persists.
• don't propose a final design. present options and a recommendation, but frame it as input for the design phase.
• don't boil the ocean. focus on what's relevant to this specific issue. if you find tangential problems, note them briefly but don't deep-dive.

6. next step

after the human reviews your findings and is ready to move forward:

/brd-design $ARGUMENTS

Converted and distributed by TomeVault — claim your Tome and manage your conversions.