Extract project vision and decisions into living docs
Interview loop that extracts a user's vision, decisions, and preferences into durable README and ADR docs.
Why it matters
Capture the user's vision, preferences, and architectural decisions through iterative interviews and automatically maintain them as structured markdown documentation (README and ADRs) that evolve with the project.
Outcomes
What it gets done
Read existing docs and ADRs before every interaction to stay current
Ask five varied, high-quality questions spanning different project dimensions
Update README or create new numbered ADR files after every user answer
Loop through interview rounds until the user signals completion
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-brain-to-docs | bash Overview
Brain To Docs
Runs a back-and-forth interview - 5 high-variety questions per round by default - to extract a user's vision, decisions, and preferences, updating README.md or a new docs/adr ADR after every single answer. Use it when a README and ADRs should be built through interview rather than written from scratch. Get explicit approval before any file-changing or remote action it triggers.
What it does
Extracts a user's taste, judgment, knowledge, vision, preferences, and decisions into durable markdown docs for a project via a back-and-forth interview loop: README holds the vision, docs/adr/ holds the decisions. Each loop iteration reads docs/adr/ and README.md first (since other agents and people edit ADRs constantly), asks 5 different, high-variety questions in plain text (never a questions UI, unless the user asked for a different number or a specific focus), then updates the docs after every single answer - deciding whether it becomes a README edit or a new ADR. It repeats until the user says they're done.
When to use - and when NOT to
Use it when the user wants to extract project vision, decisions, or preferences into durable docs, or when a README and ADRs should be built through interview rather than written from scratch. All answers and responses during the process must stay very concise, in short sentences, plain English; ADRs follow a short numbered NNNN-slug.md format with Status, Context, Decision, and Consequences sections, and the README holds vision only (decisions belong in ADRs, not the README). Don't challenge the user's thinking unless they ask or they're making a severe mistake. Being adapted from a third-party skill, verify local paths, tools, credentials, and agent features before acting, and for any commands, remote access, scheduling, browser automation, or file-changing workflows it triggers, get explicit user approval and confirm the target environment first.
Inputs and outputs
Input is the user's answers to a rolling set of interview questions, 5 by default or a different number if the user asks. Each batch is deliberately high-variety - a wide, creative spread of unique angles rather than five questions that all happen to be about the same thing, like tech stack or monetization - though a user who asks for a specific focus area gets exactly that focus instead, and picks whichever question in a round they find most useful to answer first. Output is an updated README.md and numbered ADR files in docs/adr/, updated after every single answer rather than batched at the end.
Who it's for
A project owner in the middle of an active back-and-forth session who'd rather answer one short, well-chosen question at a time than sit down and draft a README or a set of ADRs from a blank page.
Source README
brain-to-docs
When to Use
- Use when the user wants to extract project vision, decisions, or preferences into durable docs.
- Use when README and ADRs should be built through a back-and-forth interview.
The whole purpose: extract as much of the user's taste, judgment, knowledge, vision,
preferences, and decisions as possible into text - saved as clear, concise
markdown docs for the project. README holds the vision; docs/adr/ holds the
decisions.
The loop
- Check docs first, every time. Read
docs/adr/(andREADME.md) before
doing anything - other agents and people add/edit ADRs constantly. - Ask 5 different questions in plain text (never a questions UI) - default 5
unless the user asks for a different number. Make them high-variety: a wide,
creative spectrum of unique angles, not all the same type (e.g. not all "tech
stack" or all "product" or all "monetization"). Exception: if the user asks for a
specific focus area, follow it. The user answers whichever they find most useful. - Update docs after EVERY answer - no exceptions. You decide whether it
updatesREADME.mdor becomes a new ADR - whatever makes sense. - Repeat until the user says "we're done" (or similar).
Rules
- All answers & responses during this "brain to docs" process must be VERY
CONCISE, all sentences should be SHORT, and everything should be written in
PLAIN ENGLISH. - ADRs: short, numbered
NNNN-slug.md, Status + Context + Decision + Consequences. - README: vision only. Decisions go in ADRs.
- Don't challenge the user's thinking unless they ask, or they're making a severe mistake.
Limitations
- Adapted from
davidondrej/skills; verify local paths, tools, credentials, and agent features before acting. - For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.
FAQ
Common questions
Discussion
Questions & comments ยท 0
Sign In Sign in to leave a comment.