Skip to content

Continuous Improvement

The toolkit's core operating practice: every session captures learnings, every learning feeds back into the framework.

The feedback loop

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Session    │────>│   Intake    │────>│    SPEC     │────>│  Toolkit    │
│   Journal    │     │  Proposal   │     │             │     │  Update     │
└─────────────┘     └─────────────┘     └─────────────┘     └──────┬──────┘
       ^                                                           │
       └───────────────────────────────────────────────────────────┘
                    Next session benefits from the improvement
  1. Journal — use /vt-c-journal to record decisions, problems, and insights during work
  2. Propose — submit improvements to intake/pending/ when patterns emerge
  3. Specify — accepted proposals become SPECs with acceptance criteria
  4. Implement — SPECs flow through the development workflow and update the toolkit
  5. Repeat — the next session starts with the improved toolkit

Session journaling is mandatory

Journaling is not an optional extra. It is the mechanism by which the toolkit improves. The constitution (Principle III) requires that all orchestrators load institutional knowledge and that sessions capture learnings.

What to capture

Use /vt-c-journal throughout every work session to record:

  • Decisions — what you chose and why ("Used bcrypt because our deployment has native support")
  • Problems — what went wrong and how you fixed it ("Build failed because X was missing")
  • Deviations — where you diverged from the plan and why
  • Insights — patterns noticed, friction encountered, ideas for improvement

When to capture

  • After making an architectural choice
  • After debugging a non-obvious issue
  • After encountering toolkit friction or a missing feature
  • After completing a significant implementation step

The /vt-c-journal command

/vt-c-journal "Chose Redis over Memcached for session storage because our infrastructure already runs Redis and we need pub/sub for real-time features"

Each entry is timestamped and stored in the session journal for later consolidation.

From journal to intake

When the same pattern appears across multiple sessions, it should become a toolkit improvement:

  1. Run /vt-c-consolidate to synthesize journal entries into durable artifacts
  2. If a pattern repeats 3+ times, it qualifies for promotion to docs/solutions/patterns/critical-patterns.md
  3. If a workflow improvement is identified, submit an intake proposal (see Contributing to Toolkit)

The compound effect

This loop is what makes the framework self-improving. A bug found in one project becomes a pattern documented for all projects. A workflow friction in one session becomes an automated check in the next release. Over time, each unit of engineering work makes subsequent work easier — the core compound-engineering principle.

See also