dld-snapshot

name	dld-snapshot
description	Generate SNAPSHOT.md (detailed decision reference) and OVERVIEW.md (narrative synthesis with diagrams) from the decision log.
compatibility	Requires bash. Scripts use BASH_SOURCE for path resolution.

/dld-snapshot — Generate Spec Projection

You are generating documents that project the current state of the decision log into readable formats. The two built-in documents are always generated:

1. decisions/SNAPSHOT.md — Detailed per-decision reference. Every active decision with its rationale and code references.
2. decisions/OVERVIEW.md — High-level narrative synthesis with Mermaid diagrams. The document you'd hand to someone who needs to understand the system.

If the project's dld.config.yaml defines snapshot_artifacts, additional custom documents are generated as well (see Step 5).

Script Paths

Shared scripts (used indirectly via skill scripts):

../dld-common/scripts/common.sh

Skill-specific scripts:

scripts/collect-active-decisions.sh
scripts/detect-snapshot-changes.sh
scripts/update-snapshot-state.sh

Prerequisites

Check that dld.config.yaml exists at the repo root. If not, tell the user to run /dld-init first and stop.

There must be at least one accepted decision. If all decisions are proposed, tell the user there's nothing to snapshot yet and suggest /dld-implement.

Check for uncommitted changes to decision files. Run git status --porcelain -- <decisions_dir>/records/ and inspect the output. If there are unstaged or staged-but-uncommitted decision files, commit them first with a message like "Update decision records" before proceeding. This ensures the change detection script can rely on git history. Tell the user you are committing pending decision changes.

Step 1: Determine update mode

If the user's message includes --full (e.g., /dld-snapshot --full), skip change detection and use full mode for all documents.

Otherwise, run:

bash scripts/detect-snapshot-changes.sh

This outputs:

• mode: full — no prior snapshot state exists, or SNAPSHOT.md/OVERVIEW.md are missing. Proceed with full generation.
• mode: incremental — prior state exists. The output also includes:
  • new_decisions: — comma-separated list of new accepted decision IDs (e.g., DL-072, DL-073)
  • modified_decisions: — comma-separated list of existing decisions changed since last snapshot (status changes, content edits)
  • commit_range: — the git range since last snapshot (e.g., abc1234..HEAD)

If mode is incremental but both new_decisions and modified_decisions are empty, tell the user nothing has changed since the last snapshot and stop.

Step 2: Collect active decisions

bash scripts/collect-active-decisions.sh

This outputs the full content of all accepted decisions, separated by ===DLD_DECISION_BOUNDARY=== markers. Parse the output to extract each decision's frontmatter and body. Use the project mode from dld.config.yaml (already checked in prerequisites) to determine the organization strategy.

Step 3: Generate or update SNAPSHOT.md

Full mode

Write decisions/SNAPSHOT.md from scratch using the template and rules below.

Incremental mode

Read the existing decisions/SNAPSHOT.md and apply targeted edits:

1. For each new decision: Identify which group heading (## Namespace or ## Tag Group) it belongs to. Insert the new ### DL-NNN: Title section in the correct position (ascending ID order within the group). If the group heading doesn't exist yet, add a new ## Group section.
2. For each modified decision: Read its current status from the decision file.
   • If now superseded or deprecated: remove its ### DL-NNN section from the file. If the group becomes empty after removal, remove the group heading too.
   • If still accepted but content changed: replace its ### DL-NNN section with updated content.
   • If it has a new amends relationship: add an *Amended by: DL-YYY* line to the target decision's section.
3. Update the header: Adjust the "Active decisions" count, the "DL-001 through DL-XXX" range, and the date.

Do NOT rewrite the entire file. Use targeted edits to insert, remove, or modify only the affected sections.

Template

# System Snapshot

> Auto-generated from the decision log on YYYY-MM-DD. Do not edit manually.
> Use `/dld-snapshot` to regenerate. Source of truth: individual decision records.
>
> **Active decisions:** N (DL-001 through DL-XXX, excluding superseded/deprecated)

---

## <Namespace or Tag Group>

### DL-NNN: <Title>
*Supersedes: DL-XXX* ← only if applicable
*Amends: DL-XXX* ← only if applicable
*Amended by: DL-YYY* ← only if another decision amends this one

<The Decision section from the record — what was decided. Copy verbatim or lightly condense.>

**Rationale:** <1-3 sentence summary of the Rationale section. Condense, don't copy verbatim.>

**Code:** `<path>` → `<symbol>`, `<path>`

---

### DL-NNN: <Title>
...

Organization rules

Namespaced projects: Primary grouping by namespace. Within each namespace, decisions listed by ID ascending (oldest first — they build on each other).

Flat projects: Group by tag. Decisions with multiple tags appear under their first/primary tag. Decisions with no tags go under a "General" section. Within each group, decisions listed by ID ascending.

Content rules

• Only include accepted decisions
• Skip superseded, deprecated, and proposed decisions entirely
• When a decision supersedes another (check the supersedes field in the YAML frontmatter), include a *Supersedes: DL-XXX* note
• When a decision amends another (check the amends field), include an *Amends: DL-XXX* note on the amending decision and an *Amended by: DL-YYY* note on the original decision
• The Decision section content should be copied directly or lightly condensed — this is the authoritative statement
• The Rationale should be condensed to 1-3 sentences — enough to understand why, not every detail
• Code references should list paths and symbols from the frontmatter references field
• If a decision has no Rationale section, omit the Rationale line
• If a decision has no references, omit the Code line

Step 4: Generate or update OVERVIEW.md

This is fundamentally different from SNAPSHOT.md. You are synthesizing across decisions to create a readable narrative that explains the system's current design. Think of it as the document you'd give a new team member or use to onboard an AI agent on the project.

Full mode

Write decisions/OVERVIEW.md from scratch using the template and guidelines below.

Incremental mode

Read the existing decisions/OVERVIEW.md. Identify which domain sections are affected by the new and modified decisions — look at their namespaces, tags, and the topics they cover. Then:

1. Update only the affected sections. Rewrite each affected section to integrate new decisions or remove references to superseded/deprecated ones. Leave unaffected sections untouched.
2. Add new sections if new decisions introduce a domain area not covered by existing sections.
3. Update diagrams only if the changeset affects the relationships or components they depict.
4. Update the header (decision count, date) and Key Technical Choices if any new decisions are cross-cutting.

Maintaining appropriate abstraction: The overview should remain a high-level narrative, not grow into a detailed specification. As you update sections, consider whether the overall document still reads as an overview. If adding new decisions makes a section too detailed or the document too long, condense older stable content to make room — summarize established decisions more aggressively to keep focus on what matters for understanding the system. If the document's section structure no longer properly organizes the content (e.g., a new cross-cutting concern spans multiple existing sections), restructure as needed — this may mean a larger rewrite of the document, which is appropriate when the system's shape has meaningfully changed.

Template

# System Overview

> Auto-generated narrative synthesis from N active decisions. Last updated YYYY-MM-DD.
> This document is derived from individual decision records — do not edit manually.
> Use `/dld-snapshot` to regenerate.

## Architecture Overview

<If there are enough architectural decisions to warrant it, include a high-level Mermaid diagram showing key components and their relationships. Base this on the code references and decision content.>

```mermaid
graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]

<Narrative prose synthesizing the decisions in this area. Write in present tense. Explain what the system does and why, weaving together multiple decisions into a coherent story. Reference decision IDs parenthetically, e.g., (DL-012).>

<If the decisions in this area describe a flow or process, include a Mermaid diagram:>

sequenceDiagram
    participant Client
    participant API
    participant PaymentGateway
    ...

Decision Relationships

<Only include this section if there are supersession chains, amendment relationships, or closely related decision groups. If no decisions supersede or amend others and there are no meaningful relationship clusters, omit this section entirely.>

graph LR
    DL-003 -->|superseded by| DL-012
    DL-012 -.->|amends| DL-005
    DL-012 -.->|related| DL-014

Key Technical Choices

<Bullet-point summary of the most impactful cross-cutting decisions that don't belong to a single area. E.g., "PostgreSQL for primary data store (DL-001)", "All API input validated with Zod schemas (DL-008)".>

### Narrative guidelines

- **Write prose, not lists.** The snapshot already provides the structured listing. The overview should read like a design document.
- **Synthesize, don't enumerate.** Don't just list decisions — explain how they fit together. "The billing system uses banker's rounding for EU VAT calculations (DL-012), replacing the earlier truncation approach that caused reconciliation failures."
- **Use present tense.** Describe what the system *does*, not what was decided.
- **Reference decision IDs parenthetically.** Every claim should be traceable: "(DL-012)" after the relevant statement.
- **Include Mermaid diagrams where they add clarity.** Good candidates:
  - Architecture/component diagrams when decisions span multiple components
  - Sequence diagrams when decisions describe flows or protocols
  - Relationship diagrams when there are supersession chains or amendment relationships
  - Don't force diagrams if the decisions are simple or unrelated
- **Keep it proportional.** A project with 5 decisions needs a short overview. A project with 50 needs more structure. Scale the document to the content.
- **Group by namespace (namespaced projects) or by domain theme (flat projects).** For flat projects, identify natural domain groupings from tags and decision content.

### Diagram guidelines

When creating Mermaid diagrams:
- Use `graph TD` or `graph LR` for architecture/component/relationship diagrams
- Use `sequenceDiagram` for flow/protocol diagrams
- Use `flowchart` for process/workflow diagrams
- Keep diagrams focused — show the relationships that decisions actually govern, not a complete system map
- Label edges with the nature of the relationship
- Reference relevant decision IDs in node labels or notes where helpful
- **Always quote node labels** with `["..."]` to avoid parse errors from special characters
- **Escape `@` as `#64;`** inside node labels and edge labels — raw `@` breaks Mermaid parsing
- **Use `<br/>` for line breaks** inside quoted labels — do not use `\n` or literal newlines
- **Avoid special characters** (`(`, `)`, `[`, `]`, `{`, `}`, `|`, `#`, `&`) in unquoted labels — use quoted labels or HTML entities instead

## Step 5: Generate custom artifacts

Read the `snapshot_artifacts` key from `dld.config.yaml`. If the key is absent or the list is empty, skip this step entirely.

For each entry in `snapshot_artifacts`:

1. **Validate the `title`:**
   - Must end in `.md`. If not, warn the user and skip this artifact.
   - Must not collide (case-insensitive) with reserved filenames: `SNAPSHOT.md`, `OVERVIEW.md`, `INDEX.md`. If it collides, warn the user and skip this artifact.

2. **Generate `decisions/<title>`** using the collected decisions (from Step 2) as context and the `prompt` field as the generation instruction. The file must begin with this standard header:

   ```markdown
   # <Title without .md extension>

   > Auto-generated from the decision log on YYYY-MM-DD. Do not edit manually.
   > Use `/dld-snapshot` to regenerate.

Followed by the content generated according to the prompt.

Keep track of which custom artifacts were successfully generated — you will need the list for Step 6 and Step 7.

Step 6: Update snapshot state

Pass any successfully generated custom artifact filenames as arguments:

bash scripts/update-snapshot-state.sh [ARTIFACT_NAME...]

For example, if custom artifacts ONBOARDING.md and API-CONTRACTS.md were generated:

bash scripts/update-snapshot-state.sh ONBOARDING.md API-CONTRACTS.md

If no custom artifacts were generated, run without arguments:

bash scripts/update-snapshot-state.sh

Step 7: Suggest next steps

Snapshot generated:

• decisions/SNAPSHOT.md — detailed reference (N active decisions)
• decisions/OVERVIEW.md — narrative synthesis with diagrams
• decisions/<ARTIFACT>.md — <one line per custom artifact generated, if any>

Next steps:

• Review the generated documents for accuracy
• /dld-decide — record new decisions
• /dld-audit — check for drift between decisions and code