Skip to content

Include proposed decisions in snapshot and overview docs #9

@jimutt

Description

@jimutt

Problem

Currently /dld-snapshot only includes accepted decisions in SNAPSHOT.md and OVERVIEW.md. Proposed decisions are completely invisible in these generated documents. This means you can't get a full picture of the system's direction — planned but not-yet-implemented decisions are hidden until they're accepted.

After running /dld-plan to break a feature into proposed decisions, they immediately vanish from the snapshot. The only way to see them is by reading individual decision files or INDEX.md.

Proposal

Include proposed decisions in both SNAPSHOT.md and OVERVIEW.md, visually separated from accepted decisions.

SNAPSHOT.md

Add a separate section for proposed decisions, clearly marked:

## <namespace> (proposed)

> These decisions are proposed but not yet accepted. They represent planned direction, not current state.

### DL-NNN: Title

...

Or alternatively, a single "Proposed" top-level section at the bottom grouping all proposed decisions across namespaces.

OVERVIEW.md

The narrative synthesis is trickier — mixing proposed and accepted decisions in the same prose could be confusing. Options:

  1. Separate "Planned" section at the bottom with its own narrative, clearly marked as forward-looking
  2. Inline with markers — weave proposed decisions into the narrative but mark them explicitly, e.g. "(DL-NNN, proposed)"
  3. Only in SNAPSHOT.md — keep OVERVIEW.md as accepted-only, since it represents "what the system does" in present tense

Option 1 seems cleanest — the overview stays accurate for current state, with a clearly separated forward-looking section.

Why this matters

  • /dld-plan creates proposed decisions that immediately vanish from the snapshot
  • New team members or AI agents reading the generated docs miss planned work entirely
  • The snapshot is the natural place to get a complete view of all decisions

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions