seeds — research notes for a blog post

A research dump, not a draft. Pulls from the original brainstorm (plans/discussion.md), seeds about seeds, cross-project usage data, and Clancey transcripts. Quotes are verbatim from Ryan’s own writing/voice unless noted. Pick what resonates. Cut the rest.

Audience

Two readers benefit. The blog post can speak to either or both:

The intended reader: developers planning software with AI pair-programmers, who keep losing the why behind their decisions when Claude rewrites the plan file out from under them.
The wider reader: anyone — researcher, RPG GM, person planning a kitchen remodel — who deliberates by talking through tangents and wants the journey preserved, not just the destination. Seeds was deliberately designed domain-agnostic; the software-with-AI use case is just the one that hurt enough to build a tool for.

The origin story, in Ryan’s own voice

These are pulled verbatim from plans/discussion.md — the rambling pre-spec brainstorm Ryan dictated at the start of the project. They are the rawest articulation of why and should anchor the post.

The problem with markdown plan files

“The terrifying thing about that is AI seems really happy to just generate the initial document and then change it upon feedback without recording why there was a change. And it’s to the point where we are actually scared to bring feedback to AI because it’s going to overwrite the original thinking captured in the original markdown document. We’re very precious about our thinking. We’re very precious about keeping record of our thinking.”

“In the past, one of the things I’ve done is commit early and often. AI will generate the document. I’ll save it. I’ll give feedback. We’ll have more conversation. So those are all different commits, but they’re not necessarily easy to review. It’s a thorough history, but it’s not a very accessible history to me. And I don’t think it’s a natively accessible history to an AI agent either.”

“For a given idea, I would like the tool to be able to track how it evolved over time.”

The pattern this names: working with AI on a plan file is a workflow that destroys evidence. The current plan exists, the conversation that produced it does not. Git commits preserve the artifact’s evolution but not the deliberation. Asking AI for feedback is unsafe because it will helpfully rewrite away the very reasoning you wanted to challenge.

The pivot away from ADRs

The very first line of the brainstorm is the pivot:

“We are not interested in ADRs. Or at least, we are. And having a tool that maintains them is great. But what we’re actually looking for is capturing the deliberation process.”

(The seeds project is the second go at this. The first attempt was an ADR tool called ADRB — archived/adrb/ still has the research docs Ryan commissioned on deliberation software. Those docs surfaced the framing that ADRs / RFCs / design docs all capture conclusions, not the journey, and that no widely-adopted tool exists for the journey.)

The seed metaphor

“The project is called SEEDS because the idea is we will have the seed of an idea and we will, through interaction with the tool, water, nurture, metaphorically help this seed sprout and turn into a full-grown set of ideas and decisions about what it is we want to do.”

The metaphor does work: a seed is an idea that hasn’t earned the right to become a task yet. It needs time. It might never grow at all and that’s fine. A todo list can’t hold this.

The “mind racing” capture problem

“My mind races. When I start talking about one idea, I might have six or seven other ideas, some that are related, some that are totally different, but I just want to get down on paper somewhere before I go back to trying to focus on the original idea I was working on.”

“Ideas can split into two different ideas. Ideas can merge into a single idea. One idea can spark a new idea. One idea can override another.”

This is the design pressure behind seeds jot — minimal-friction capture that doesn’t require titles, types, parents, or context-switching. It’s also the design pressure behind hierarchical IDs (seed-a1b2.3), bidirectional links, and the lifecycle-with-deferred state. The tool’s shape is dictated by the texture of how Ryan actually thinks.

Domain-agnostic from the first sentence

“It’s not just going to be limited to software. I’m involved in a role-playing game and the decisions that went into what to do with my character development would have been a perfect application of a decision-making tool as well. I can think of almost anything I’m doing — house projects, stuff like that — where I want to capture things I’ve considered, explorations I’ve made in those considerations, questions that have come up and that need to be answered along the way.”

The domain-agnostic ambition is explicit and original to the project, not a post-hoc generalization. The deliberation pattern is the same across domains even when the “fruit” differs (ADR for software, character backstory for RPGs, shopping list for house projects).

Why the AI matters specifically

“One of my major surprises in using beads is how much Claude just uses it like it’s an extension of itself. You can just watch it absorb that tool and work with it so easily and so naturally. I want a similar tool in seeds because if I’m having a conversation with an AI agent as we’re planning something out, I want it to just intuitively understand: in my feedback to the agent, there’s three different considerations, maybe some answers, maybe some questions that need to be generated.”

Seeds is built on a specific bet: that giving the AI a structured place to put thoughts changes how the conversation goes. Without it, deliberation is ephemeral — it lives in chat scrollback that gets compacted and lost. With it, the AI has somewhere to externalize its reasoning that survives the session.

The honest fear

“I’ve never had a formalized decision-making process. I don’t have a system in place. It’s always been very ad hoc, always been very nebulous, for 25 years of professional development and 43 years of existence. I get nervous when I’m supposed to write software for a thing that isn’t already modeled as a system somehow.”

This is a humility note worth keeping — the post is more interesting if it acknowledges that the tool was built by someone who didn’t have a system, not someone evangelizing one.

Philosophy (synthesized from many seeds)

“Capture the journey, not just the conclusions”

This is the cleanest one-line philosophy and it surfaces over and over:

From seeds-83.4 (a decision recorded after researching Context Portal):

“ConPort stores conclusions; seeds tracks the journey.”
From seeds-12.2 (“Seeds as philosophy vs tool”):

“When you’re deciding what to build, you shouldn’t be in the same mental space as tracking what to build. Mixing deliberation artifacts with implementation tasks muddies both. A developer looking at bd ready wants actionable work items, not half-formed questions about whether the architecture is right.”
The README tagline (resolved in seeds-111):

“Git-backed deliberation capture for ideas that need time to grow.”

Two lifecycle models, not one

From seeds-12.1 (whether beads has absorbed seeds’ purpose):

“Beads: open → in_progress → closed (execution lifecycle) Seeds: captured → exploring → resolved/abandoned/deferred (deliberation lifecycle)”

“Beads assumes everything is work to be done. Seeds assumes everything is a thought that might become work someday. These are genuinely different lifecycle models.”

This is the strongest argument for the tool’s right to exist alongside beads. A todo tracker has no good place for “I had a thought, I don’t know if it’s anything yet, I don’t want to forget it, but please don’t put it in my todo list.”

Inbox, not backlog

From seeds-14:

“Capture fast, refine later. Get the idea into the system as quickly as possible. Review later to: tag and refine, establish relationships, put in right categories, achieve ‘inbox zero’.”

seeds jot is the realization of this. No prompts, no required fields, just a sentence and a generated ID. The structure can be added (or never added) later.

Questions are first-class objects

This emerged from dogfooding. Several abandoned seeds (seeds-43, seeds-19, seeds-32, seeds-33) document the iterations where the team treated questions as prose-inside-seeds, hit friction, and finally promoted questions to their own entity with their own status (open/answered/deferred). Captured in seeds-51 as a meta-observation:

“The tool’s design gaps become visible through use. This is valuable — dogfooding reveals issues. Implication: keep using seeds to design seeds.”

AI-as-participant, not AI-as-secretary

From seeds-7 (consolidated from earlier observations):

“AI suggesting status changes during conversation feels like natural collaboration — draws attention to next steps.”

“Conversational feedback should flow into seeds — AI should recognize when to capture insights.”

“AI should propose triage/organization rather than asking user to do it — reduces cognitive load.”

The vision is not “Ryan dictates, AI types into seeds.” It’s “AI participates in the deliberation, captures its own reasoning, raises its own questions, proposes its own conclusions, and Ryan steers.” The prime command exists specifically to bootstrap this — it dumps deliberation context into the agent’s working memory so the agent knows what it’s already considered.

What seeds looks like when it works (cross-project evidence)

Seeds is initialized in 9 projects under ~/projects/outins/. Usage varies wildly — that variance is the most interesting thing in the data.

marketscan_mdcd — the “ETL audit log” pattern

Healthcare claims data ETL project. 158 seeds, 154 resolved, 4 abandoned, 0 left captured/exploring. Created in a tight 1-week burst (Feb 5–12, 2026). Sample resolved-seed titles:

DECISION: BOE, MAS, MCASENUM ignored for now — no good GDM target table to store Medicaid eligibility codes. Can revisit if a patient_attributes or similar table is added.
DISCREPANCY: F table generators missing
Validate: REVCODE by FACPROF distribution
MDCD managed care (CAP=1) drives PAY=0/NETPAY>0 pattern: 33% of managed care dual claims have PAY=0 but NETPAY>0 (shadow pricing). This is capitation, not a data quality issue.

These aren’t tasks. They’re a running ledger of “things we noticed, investigated, decided about, and can now move past.” A future ETL on a similar dataset can read this and skip the rediscovery. This is what “capture the journey” looks like in production: the deliberation is the artifact, and it’s queryable.

The feedback Ryan gave during this work, captured in seeds-60:

“Seeds is wildly successful for ad-hoc exploration, but doesn’t ensure you’ve dotted all I’s and crossed all T’s. The issue: seeds lets you explore freely but doesn’t tell you what you HAVEN’T explored yet.”

seer_medicare_lung_2026 — the clean audit pattern

Smaller variant of the same shape. 7 seeds, all 7 resolved. Titles like Audit: Generator Pattern Consistency, ADI Gap: 6 ADI Columns Missing Generators, Decision: What new vocabularies are needed for 2026 socioeconomic vars?. A focused-scope project where seeds was the audit trail and every entry got closed out.

code_collector — the architecture-deliberation pattern

Code-set-catalog data extraction project. 57 seeds, 29 captured, 26 deferred, only 2 resolved. Very different shape from the ETL projects: the seeds are mostly long-running design questions and deferred subseeds of an early scaffold (seeds-1.x family) that got later subsumed.

This project produced one of the strongest companion docs: code_collector/docs/extraction_deliberation.md — a 593-line “what we considered and rejected” record written explicitly because

“I don’t want it to just get lost. So create that document as well, like extraction_deliberation.md in the docs folder.”

The doc captures Alternatives A–F that were debated and rejected during a design session, the user philosophies that surfaced (each with a verbatim Ryan quote), the seven discarded seed candidates that were proposed but not promoted, the Q1–Q9 deliberation in detail. This is the fruit of seeds-style thinking even when the seeds themselves don’t capture all of it. The seeds caught the decisions; the companion doc caught the rejected alternatives.

A money quote from the end of that doc, worth lifting for the blog:

“This deliberation took most of a workday and generated ~10 seeds, 3 architecture-relevant documents, and substantial back-and-forth on nuance. It’s tempting to feel like that’s a lot of overhead for one source. But the goal was never to profile cms_ccw efficiently — it was to build the tooling and understanding that lets us profile the other 30+ sources autonomously. Every hour spent on this deliberation should save 5 hours on source #10 because the questions won’t need re-asking.”

This is the ROI argument for deliberation capture in one paragraph.

code_set_catalog — the active design pattern

Django/pgvector catalog application. 78 seeds, 58 still captured, only 9 resolved. Tag-rich (tech-stack, data-model, mvp, alpha, rejected), with seeds like:

seeds-31: Tech stack: Django + DRF, Next.js, Postgres + pgvector, BioLORD, MCP wraps REST [tech-stack, architecture, mvp]
seeds-34: Home-grown vocabulary_codes table rejected — OHDSI is the reference substrate [rejected, vocabularies, ohdsi, data-model]
seeds-39: Family / hierarchy model — formal definition and per-vocabulary logic [data-model, hierarchy, vocabularies, open-question]

This is the shape that probably matters most for the blog: a project still in deliberation, where seeds is the medium for working out the design before code gets written. The rejected tag is doing real work — it preserves dead ends so they don’t get rediscovered.

seeds itself — the meta pattern

The seeds project’s own seed database has 122+ resolved seeds (and counting), driving its own design. Every feature in the README came out of a seed. The honest dogfooding produced specific course corrections:

seeds-43 (abandoned): “Questions should not live as prose inside seeds — they need their own status tracking” — caused the question-as-first-class refactor.
seeds-31 (resolved): A bug ticket about seeds show truncation in the terminal. Fixed via --output-file flag.
seeds-31.2 (resolved): A meta-seed: “Using seeds to document fixing seeds’ own usability problem.”

seeds-51 is the explicit articulation:

“The tool surfaces its own design issues through usage friction. Example: the insight ‘questions should not live as prose inside seeds’ emerged from actual friction when we tried to partially answer questions in [an earlier seed]. The tool’s design gaps become visible through use.”

Honest take — what hasn’t worked

The blog post is more credible if it includes the not-working parts.

Two of nine projects never used it after `seeds init`

beads/.seeds/seeds.db and agent_assessor/.seeds/seeds.db were initialized and contain zero seeds. Whatever made the developer reach for seeds init in those projects didn’t translate into actual usage. Possible reasons:

The projects had clear-enough goals that there was nothing to deliberate.
The friction of switching from “talking” to “running seeds jot” was still too high in those contexts.
The work happened in a session that didn’t have the seeds habit yet.

Either way: just installing seeds doesn’t create deliberation. The habit has to come with it.

The “completeness” gap, named in `seeds-60`

“Seeds doesn’t ensure you’ve dotted all I’s and crossed all T’s. The issue: seeds lets you explore freely but doesn’t tell you what you HAVEN’T explored yet. No way to say ‘here are 20 source tables, have I made a decision about each one?’”

Seeds is a forest of considered ideas. It doesn’t tell you what you forgot to consider. The mani project’s 5 abandoned seeds are mostly initial-scaffold seeds that got discarded when the project pivoted — the seeds themselves didn’t surface that the pivot was needed. That came from outside.

The capture gap, `seeds-112`

“Capture gap: questions must be persisted to disk when they arise, not after they’re answered.”

The friction of reaching for the CLI mid-conversation means agents (and humans) tend to capture resolved deliberation, not active deliberation. The journey is partly reconstructed from memory rather than written down live. This is partly an integration problem (slash commands, hooks, MCP) and partly a behavioral one. It’s open.

AI friction patterns (abandoned seeds 47, 48, 25)

Recorded in real time during early use:

seeds-47: “AI friction: hesitation to capture in real-time, kept asking permission instead of just recording.”
seeds-48: “AI friction: conflated ‘decision made’ with ‘go implement’ — jumped to code prematurely.”

These were abandoned because the underlying tendencies are mitigated, not solved. The agent still occasionally asks permission to jot. The agent still occasionally pivots straight from “decision” to writing code. These are patterns to watch, not problems to claim solved.

Existential question still open

seeds-12.x family asks whether beads (which has gained wisps, molecules, threading, typed relationships, metadata) has absorbed seeds’ domain. The answer Ryan reached in seeds-12.1 is “no, the lifecycle models differ” — but the question itself shows the tool’s place in the ecosystem isn’t settled. A future world where beads grows a deliberation mode and seeds is no longer needed is plausible. The blog should probably acknowledge that without flinching.

What success doesn’t look like

Worth saying explicitly: seeds doesn’t replace having good ideas, it preserves them. A bad deliberation captured in seeds is still a bad deliberation. The tool’s leverage is multiplicative on whatever quality of thinking the user brings. The marketscan_mdcd 158-seed log is impressive because the underlying ETL work was good, not because seeds made it good.

Useful counter-perspectives

Why this pattern is unusual in the existing tooling landscape

From the research doc Ryan commissioned (docs/what_i_know_about_deliberation_and_decision_making.md):

“ADRs, RFCs, and design docs all focus on outcomes or proposals, not the exploration journey… A deliberation tool needs to be lightweight enough to actually use during exploration while structured enough to be queryable.”

Existing taxonomy:

Decision logs / ADRs: capture committed decisions only.
RFCs / design docs: capture proposals and rationale, but at the level of formal artifacts, not in-flight thinking.
Issue trackers (Jira, Linear, beads): capture work, not thoughts.
Note-taking tools (Obsidian, Notion): capture content, not lifecycle.
Structured argumentation (IBIS, Compendium): capture deliberation formally, but the formality is the friction that kills adoption.

Seeds slots into a niche the existing categories miss: the lightweight, queryable, lifecycle-tracked, AI-readable deliberation log.

Why beads-the-tool inspired seeds-the-tool

From the README acknowledgment:

“Seeds was inspired by Steve Yegge’s beads project and its core insight: giving AI agents structured tools improves how agents work, bridges AI-human communication, and unlocks AI potential not accessible through unstructured conversation alone.”

This is the line worth crediting in the post: structured tools change what AI agents can do, in ways that are easy to underestimate until you watch it happen.

Suggested skeleton (if you want one)

A possible flow for the post — reorder/cut freely:

The fear: open with the “AI rewrote my plan and I lost the why” hook. Lead with the discussion.md quote about being “scared to bring feedback.”
The pivot: from ADRs (capture conclusions) to seeds (capture journey). Quote the “we are not interested in ADRs” line.
The metaphor: an idea is a seed. Some grow, some don’t, all deserve a place to wait that isn’t a todo list.
What it looks like in practice: the marketscan ETL audit log, the code_collector deliberation companion doc, the meta seeds-designing-seeds pattern.
The philosophy section: capture-the-journey, two lifecycles, inbox pattern, AI-as-participant.
The honest part: 2/9 projects never used it; completeness gap; capture gap; existential question vs. beads.
Why this might matter beyond software: domain-agnostic from day one; the deliberation problem isn’t a code problem, it’s a thinking-with-others (including AI) problem.
What’s next / call to action: it’s open source, MIT, beta, repo at outcomesinsights/seeds.

Quote bank (verbatim, for the speechwriter)

Sorted by likely usefulness in prose. Most are from plans/discussion.md; a few from seeds content fields.

“We are not interested in ADRs. What we’re actually looking for is capturing the deliberation process.”

“AI seems really happy to just generate the initial document and then change it upon feedback without recording why there was a change.”

“We are actually scared to bring feedback to AI because it’s going to overwrite the original thinking.”

“We’re very precious about our thinking. We’re very precious about keeping record of our thinking.”