edawise

Deccy Framework

Edawise

What is deccy?

deccy is a decision management framework we developed, from first principles, to perform software engineering with AI.

A codebase is some sequence of decisions, that are related in a vaguely hierarchical way

  1. You start with high-level decisions (I want to make a todo app)
  2. Gradually, you refine those decisions (What features should this app have? What platforms should it support? What language/framework should I use?)
  3. You refine them further (How does the “mark complete” feature work?)
  4. And further (When I mark an item as complete, what happens to the item?)
  5. Then you translate those into implementation decisions (schemas, data structures)
  6. And finally into actual implementation (code)

With deccy, we model the decisions made in a codebase with a directed acyclic graph:

  • Everything is a decision, from broad feature requests, to data schemas and even implementation code
  • Each decision can depend on several decisions that precede it
  • Each decision can influence several decisions
  • Every decision is justified with a rationale
  • Every decision is evaluated against the decisions it depends on

Evaluation is a core part of deccy: when making a decision, we implicitly ask questions like “Does this make sense? Does it go against other decisions? Does it satisfy my intent?”. As such, we designed deccy to require that every decision is evaluated against every parent that it depends on.

flowchart LR
  classDef decision fill:#ffffff,stroke:#1f2937,stroke-width:1.5px,color:#111827
  classDef evaluation fill:#f5f3ff,stroke:#7c5cff,stroke-width:1.5px,stroke-dasharray:5 3,color:#3b2b7a

  LG1["Decision"]:::decision
  LG2("Evaluation"):::evaluation
  LG3["Decision"]:::decision

  LG1 -->|depends_on| LG2
  LG2 -.->|evaluates| LG3
  LG1 -->|depends_on| LG3

We made it in three parts:

  • deccy-cli provides a CLI tool which encodes most of the framework
  • deccy-agent is a set of custom agents that we use
  • deccy-viewer visualises the decisions made and their relationships

How do I use deccy?

First, it helps to install deccy-cli. Then, you’ll have to decide what types of decisions matter to you. For deccy-cli, we went with high level text decisions for intent, refined them with models written with EARS and Quint, and wrote the implementation with Rust. You’ll also want to choose how to evaluate these decisions - we chose simple non-contradiction checks for text and EARS decisions, checks for Quint models and tests for Rust code.

flowchart TD
  classDef decision fill:#ffffff,stroke:#1f2937,stroke-width:1.5px,color:#111827
  classDef evaluation fill:#f5f3ff,stroke:#7c5cff,stroke-width:1.5px,stroke-dasharray:5 3,color:#3b2b7a

  subgraph intent["Intent — plain text"]
    nzrnrlky["C-DRAFTS<br/><small>`deccy drafts` is one verb: invoked bare, it lists the registry's records...</small>"]:::decision
  end

  subgraph ears["Model — EARS"]
    qspsyqlp["EARS<br/><small>When invoked bare, the deccy CLI shall list every record in the draft registry...</small>"]:::decision
  end

  subgraph rust["Implementation — Rust"]
    kpkplmqy["M-verb-drafts<br/><small>src/verb_drafts.rs</small>"]:::decision
  end

  wtnnxtql("gate: EARS<br/><small>1. License, applied once per prerequisite in depends_on: no element of the...</small>"):::evaluation
  rvpsuzys("gate: M-verb-drafts<br/><small>tests/verb_drafts/Cargo.toml<br/>tests/verb_drafts/Cargo.lock<br/>tests/verb_drafts/src/lib.rs</small>"):::evaluation

  nzrnrlky --> qspsyqlp
  qspsyqlp --> kpkplmqy
  nzrnrlky --> kpkplmqy

  nzrnrlky --> wtnnxtql
  wtnnxtql -.-> qspsyqlp

  nzrnrlky --> rvpsuzys
  qspsyqlp --> rvpsuzys
  rvpsuzys -.-> kpkplmqy

We chose one intermediate “layer”, but depending on factors like scale, complexity or stakes of your project, you may choose more (or fewer) layers. Crucially, each decision should be a sufficiently small logical step (by your chosen standard) from the decisions it depends on.

deccy-agent is our set of helper agents for managing decision graphs. It comes with the steps to turn a proposed feature or change into a modification of the decision graph. The workflow using deccy-agent looks something like this:

  1. You tell the deccy-plan agent about your intended change
  2. The planner agent reads the graph, determines the right starting location(s) for your change
  3. You review and refine the plan, then pass it to the deccy-orchestrator agent
  4. The orchestrator kicks off the workflow:
    1. It creates skeletons for any new decisions and evaluations
    2. Then, it starts subagents which draft the evaluations and decisions, before a final subagent judge assesses quality
    3. Any problems are surfaced for you to deliberate on, before the drafts are merged into the decision graph
  5. You review the changes and, once approved, the orchestrator closes the round

To view and navigate the graph more easily, use deccy-viewer, a VSCode extension which displays the decision graph and provides a search feature.

FAQ

Why deccy?

We find software engineering with AI is broken. Producing slop has become too easy, but producing good software has ironically become more difficult. More on that here. Instead of producing more software that’s (barely) tolerable, why shouldn’t we direct the power of AI into crafting great software?

Why not Spec-Driven Development?

deccy is very similar to SDD! The key difference is that specs are broken up into unit decisions, with relationships between decisions more explicitly mapped. Historically, this required a lot of upfront work which was rarely justified. Now with AI, most of that work is cheap, and it’s much more justified to make these mappings once and early, than to rediscover them every time.

Will this become obsolete when models improve?

Probably not. While we initially made this to overcome the shortfalls of LLM agents, we’ve discovered that we humans are really the problem. As most software engineers and project managers are aware of, humans are notoriously poor at defining their demands clearly. This problem is amplified by AI, and the practice of deploying before we have understood the demand. deccy provides a sensible pacing, the grill-me effect by design and a way to identify and correct incorrect decisions with minimal blast radius.

This is cool! How can I get involved?

Thanks! The quickest way to get involved is to use deccy - we want to explore what deccy can and can’t do - and send your feedback to us at hello@edawise.com. Or send us an email to discuss other ways we could work together, we’d love to hear from you!

This sucks

Please let us know why at hello@edawise.com! We know that deccy has a long way to go, and we’re working hard to improve it, so all feedback is very welcome.

I don’t know how to use this for my specific use case

Drop us an email at hello@edawise.com! We’d love to help