Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/davidbuenov/dbv-specs-ops/llms.txt

Use this file to discover all available pages before exploring further.

Every AI assistant has a finite context window, and every session eventually ends. In long-running software projects — the kind that span days, weeks, or team members — the silent loss of accumulated engineering knowledge between sessions is one of the most expensive hidden costs of AI-assisted development. dbv-specs-ops addresses this directly with a two-file context architecture: memory.md and task.md. These files are not optional organizational conveniences; they are the primary mechanism by which the framework eliminates AI amnesia and keeps token consumption predictable across the full project lifecycle.

​
The Two Context Files

The boundary between the two files is intentional and must be maintained precisely.

​
memory.md — Qualitative Knowledge

memory.md is the project’s persistent engineering brain. It stores knowledge that has no expiry date: the reasoning behind decisions, the lessons extracted from failures, and the current focus area of the product. It is designed to be read by the AI at the start of every session to reconstruct the technical thread. Its four sections serve distinct purposes:
  • Active Context (## 🎯 Contexto Activo): A brief description of the current development state and the immediate focus area. Updated when the project’s direction changes significantly.
  • Technical Decisions Log (## 🏗️ Log de Decisiones Técnicas): A lightweight ADR (Architecture Decision Record) log. Each entry explains why a technical route was taken — library choices, architectural pivots, security tradeoffs — with a date. This is where the Adversarial Architect Review deposits accepted risks.
  • Lessons Learned (## ⚠️ Lecciones Aprendidas): Notes on specific bugs, failed configurations, or refactors that must not be repeated. These entries protect future sessions (and future developers) from re-discovering the same pitfalls.
  • Relations Map (## 🗺️ Mapa de Relaciones): A brief description of how current modules interact — their responsibilities and dependencies — so the AI can navigate the codebase without reading every file.

​
task.md — Operational State

task.md is the project’s real-time logbook. It stores data that is precise, time-stamped, and task-bound: the active checklist, the backlog, and the Context Snapshot — the exact re-entry point for the next session. Where memory.md answers “why did we build it this way?”, task.md answers “where exactly did we stop, and what is the next concrete action?” If information is useful for both files, the routing rule is clear: data with a specific date or step → task.md; reasoning, lessons, and architectural decisions → memory.md.

​
Memory Trigger Rules

The AI does not wait for the end of a task to update memory.md. Specific in-workflow events act as Memory Triggers that require immediate updates:
  • During /build: If the implementation modifies or contradicts a decision already documented in docs/ARCHITECTURE.md, the AI records it in memory.md under ## 🏗️ Log de Decisiones Técnicas immediately — not deferred to /ship.
  • During /test: If a test reveals that a documented assumption in docs/SPECIFICATIONS.md was incorrect, the AI records it in memory.md under ## ⚠️ Lecciones Aprendidas immediately.
  • During /plan: If the Adversarial Architect Review identifies a risk that is consciously accepted, it is logged in memory.md before the plan proceeds.

​
The Memory Gate in /ship

At the end of every task cycle, the /ship phase includes a mandatory Memory Gate. Before the task can be closed, the AI must print a structured XML block in the chat that makes the knowledge extraction decision explicit and visible: 
<memory_update_proposal>
  <section>Lecciones Aprendidas</section>
  <entry>
    The Stripe webhook handler requires an idempotency check against
    the processed_events table. Without it, network retries cause
    duplicate order fulfillment. The fix was to check event_id
    before executing the fulfillment service.
  </entry>
</memory_update_proposal>
If the completed cycle produced no new architectural decisions or lessons — for example, a minor style refactor — the AI must still print the block, but with an explicit justification: 
<memory_update_proposal>none</memory_update_proposal>
<reason>
  This cycle was a minor CSS refactor with no new architectural
  decisions, dependency changes, or discovered bugs. No persistent
  knowledge was generated.
</reason>
This gate prevents the silent degradation of memory.md over time — every session either adds verified knowledge or explicitly confirms there is nothing to add.

​
Context Snapshots in task.md

A Context Snapshot is a brief structured entry written at the bottom of task.md whenever a session is about to end or a conversation is approaching its token limit. It contains exactly the information needed to resume work without any loss of precision. A Context Snapshot records:
  • The date of the last update
  • The exact point reached in the current task
  • What remains pending (the next concrete action)
  • The immediate next step in specific, actionable terms
Here is an example from a real dbv-specs-ops project session: 
## 🔄 Context Snapshot

> **Last update:** 2026-06-17
> **Exact point:** Version 2.1.0 (Agent Readiness Integration) completed
>   and documented in walkthrough and changelog.
> **Pending:** Execute commit and tag in the local repository.
> **Next step:** Inform the human user of the successful release and
>   provide the Git commands for push.
The Snapshot is written proactively — the AI does not wait for a crash or a token error. Whenever the current conversation is nearing its end, writing the Snapshot is the final step before closing.

​
The “Consult First, Update After” Pattern

The two-file architecture is governed by a single behavioral rule that applies at every session boundary:
  1. Consult first: Before proposing any code, the AI reads project.config.md, SPECIFICATIONS.md, memory.md, and task.md. Consulting memory.md at the start of every session is mandatory — it is the only way to recover the technical thread.
  2. Update after: After each milestone, the AI updates the operational state in task.md and proposes updates to memory.md when a decision, deviation, or lesson has emerged.
This pattern means that memory.md and task.md are always consistent with the actual state of the project — not a stale snapshot from weeks ago.

​
Practical Example: Resuming a Session

Imagine returning to a project after a week away, or switching from Claude to Windsurf mid-project. The resume sequence is:
  1. Open your AI assistant. The activation file (CLAUDE.md, GEMINI.md, .windsurfrules) loads MASTER_PROMPT.md automatically.
  2. The AI reads memory.md → recovers architectural decisions, active context, and lessons.
  3. The AI reads task.md → finds the Context Snapshot with the exact next step.
  4. The AI reports its understanding: “Last session completed version 2.1.0. The pending action is to confirm and push the Git tag.”
  5. Development resumes from the precise point where it stopped — no re-explanation, no reconstruction, no duplicated work.
This sequence works across token limits, platform switches, and multi-day gaps because the context was written down, not held in the model’s ephemeral session memory.
Memory Maintenance Policy: memory.md must stay under approximately 200 active lines. When it grows beyond this threshold — or on any Major version /ship — the AI applies the maintenance policy: consolidate related decisions into single entries, archive fully-internalized lessons to memory.archive.md, and delete entries that describe reverted or obsolete decisions. The goal is that the AI can always read memory.md in its entirety in a single context load without loss of attention.

Build docs developers (and LLMs) love

Get started for freeTalk to us