Skill

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.


81
Spark score
out of 100
Updated 15 days ago
Version 1.0.0

Add to Favorites

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

01

Read existing docs and ADRs before every interaction to stay current

02

Ask five varied, high-quality questions spanning different project dimensions

03

Update README or create new numbered ADR files after every user answer

04

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

  1. Check docs first, every time. Read docs/adr/ (and README.md) before
    doing anything - other agents and people add/edit ADRs constantly.
  2. 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.
  3. Update docs after EVERY answer - no exceptions. You decide whether it
    updates README.md or becomes a new ADR - whatever makes sense.
  4. 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.