decision-log-writer

Documenting architecture decisions involves recording the decision, alternatives, rationale, consequences, and date in a structured entry. This skill scaffolds those entries into a centralized log using standardized templates under .documents/_ops/DECISIONS.md.

Design decision logs should be structured with dedicated sections for Decision, Alternatives, Rationale, Consequences, and Date. Using a scaffold script and standardized markdown templates ensures consistency across entries and preserves critical context for future reference.

Yes, you can automatically scaffold dated decision log entries by running the scaffold_doc.py script, which populates a new date-stamped subsection in the target DECISIONS.md document using a predefined markdown template.

This decision logging approach works within markdown documentation workflows by appending date-stamped subsections to a centralized DECISIONS.md file. Guardrails restrict writes to the .documents/ directory and reference CHECKLIST.md for quality assurance.

A key limitation is that all decision entries must reside under the .documents/ directory path. The logging mechanism relies on append mode for dated subsections, meaning it is structured for chronological, centralized markdown accumulation rather than distributed tracking.

You need a formal decision log when capturing architecture decisions, data-model tradeoffs, or design-review outcomes where preserving the rationale and context behind choices is critical for long-term project operations and team alignment.