run-design-decision

Design Decision Management

You are creating or updating a design decision document — architectural choices, patterns, and their rationale.

Prerequisites

Directives: If docs/ritual-config.json exists, read directives.documentation from the config. These are soft guidelines that influence your documentation style, detail level, and terminology. Apply them when writing decision docs. If the field is missing or empty, proceed without directives.

Creating a new decision doc

1. Determine the topic from context or user request
2. Check alignment upward: grep docs/domain/ for related tags and read matches. Verify the decision doesn't violate any domain rules.
3. Write to docs/decisions/<kebab-case-title>.md:

---
title: "<descriptive title>"
type: decision
tags: [<lowercase, hyphen-separated, matching module/directory names>]
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>
---

## Decision
<What was decided>

## Context
<Why this decision was needed>

## Rationale
<Why this option was chosen over alternatives>

## Constraints
<Domain rules that influenced this decision>

4. Commit:

git add docs/decisions/<filename>.md
git commit -m "docs: add design decision — <title>"

Updating an existing decision doc

1. Read the existing doc
2. Check alignment with domain knowledge (upward)
3. Make the update
4. Update the updated date
5. Commit

After writing (cascade)

Design decisions sit in the middle tier. Check both directions:

1. Upward check (already done): alignment with domain knowledge
2. Downward cascade: dispatch run-clash-check as a subagent targeting docs/specs/. This is a depth-1 cascade — run-clash-check must NOT trigger further cascades.

Report:

• What was created/updated
• Any alignment issues with domain knowledge
• Any clashes with specs detected by the subagent