Solve System

A framework for tracking dependencies between pieces of work and a Claude Code command system that implements it.

New here? Start with the /solve command guide.

Two Layers

Solve Graph is the conceptual model. It organizes work as a directed acyclic graph of objectives, where each objective declares what it reads (references), what it produces (results), and how it connects to other objectives. When an upstream artifact changes, the graph identifies exactly what downstream work is affected. It is not a task tracker — it manages dependencies between artifacts.

Solve Command System is the Claude Code implementation. It provides six commands and file conventions that guide a problem from initial framing through iterative refinement, commit, and archival.

How It Works

Each unit of work is an objective represented by a solve file (.solve.md). The solve file captures the problem/goal, constraints, principles, decisions, open questions, and references — everything an agent needs to work on the problem.

Objectives connect through dependencies: when one solve file references another's result, a versioned link is created. Staleness is detected by comparing pinned versions against current versions — no central manifest needed. The graph is derived by scanning files.

Commands

Command	Purpose
/solve	Entry point for all sessions (new and resumed). Frames the problem through structured dialog, produces the solve file.
/solve-refine	Iteratively improves output files within a stage. Bumps minor version each cycle.
/solve-commit	Snapshots a stage, extracts higher-scope knowledge, optionally deploys, creates a git commit.
/solve-archive	Moves a completed solve to solves/archive/. Terminal state.
/solve-find-stale	Forward impact analysis — finds stages affected when a stage's outputs change.
/solve-move	Moves files/folders and updates all references in both directions.

Key Concepts

• Solve file is the primary deliverable, not the solution. The solution verifies that the solve file is sufficient.
• Sub-agent verification: A sub-agent reads only the solve file and produces the output. If it can't produce a comparable solution, the solve file has gaps.
• No cycles internally: The graph is a strict DAG. Upstream feedback uses the deployment mechanism (content placed as an ingested file, not an internal link).
• Staleness is informational: The system surfaces what's stale; the user decides what to revisit.
• Scoped knowledge (solve-context.md): Reusable insights extracted at commit time, tagged by scope (personal, team, company).

File Conventions

solves/
  <solve-folder>/
    <name>.solve.md        # Solve file — the primary artifact
    <name>.solve-log.md    # Change log (per-session sections)
    <name>.solve-output.md # Default output file (can live anywhere)
    references/            # Shared references (multi-stage)
  archive/                 # Completed solves
  solve-context.md         # Accumulated higher-scope knowledge

Solve files carry YAML frontmatter with solve-version, references (path + pinned version + semantic name), and results. Output files carry a back-link to their producing solve file and the version at generation.

Design Documents

• Solve Graph Overview — conceptual model: nodes, edges, versioning, staleness, deployment
• Solve Command System — command definitions, lifecycle, file conventions, scoped knowledge
• /solve Command Spec — detailed specification for the /solve command