graven.aiBlog

March 27, 2026 · 7 min read

How we extracted 207 decisions from an existing project

We had a project with 9 design stages, hundreds of pages of context, and a working product. What we didn’t have was a map of our own decisions.

This is the story of connecting Graven to an existing project and building a complete decision graph — not from a clean slate, but from a codebase that already had history, opinions, and implicit knowledge baked into every line.

The problem with existing projects

New projects are easy. You make decisions, you record them, the graph grows organically.

Existing projects are hard. Decisions are already made. They live in code structure, config files, git history, comments, and the team’s collective memory. Nobody sat down and said “let me write down why we chose PostgreSQL.” They just chose it and moved on.

The 8-phase playbook

We built a systematic process. Not “go read the code and write down what you find.” A structured extraction with specific lenses for each pass:

  1. Phase 1: Architecture scan. package.json, Dockerfiles, CI/CD. Why this framework? Why this database? Why this deployment target?
  2. Phase 2: Data model. Migrations, schemas, type definitions. Why is this field nullable? Why soft delete?
  3. Phase 3: Business logic. Validation rules, permissions, pricing code. Every hardcoded value encodes a decision someone made.
  4. Phase 4: Integration boundaries. External APIs, auth providers, payment systems. Why this provider? What are the constraints?
  5. Phase 5: Assumption audit. Review every recorded decision — what assumption does it rely on? What breaks if it’s wrong?
  6. Phase 6: Open questions. Issue tracker, PR discussions, TODO comments. What does the team know it doesn’t know?
  7. Phase 7: Lessons learned. Git refactors, reverts, hotfixes. What went wrong? What would you tell someone to avoid?
  8. Phase 8: Validation. Review all proposed relationships. Check for gaps. Verify completeness.

What we found

207 decisions, assumptions, constraints, and lessons. Things we “knew” but had never articulated. Things we’d forgotten we decided. Things that turned out to depend on each other in ways we hadn’t realized.

The AI enrichment engine processed each entity, found 25 semantically related candidates, and proposed relationships. After review: 1,200+ confirmed connections.

The surprise

Our tech stack decision — “NestJS + PostgreSQL + Supabase” — turned out to have 178 downstream dependencies. 86% of the project. One decision, and nearly every other choice in the system traces back to it.

We knew it was important. We didn’t know it was that important.

The onboard command

Once the graph was populated, we tested: new agent, fresh session, zero context.

get_context(intent="onboard")

The agent received the full knowledge map of the project. Not 40 pages of documentation. Not a CLAUDE.md that’s perpetually out of date. A live, connected, versioned graph of every decision that matters.

It took an afternoon to extract. The graph will be useful for the lifetime of the project.

The playbook is built into Graven: setup(action="onboard_existing"). Your agent follows it step by step.