majiayu000 Dialogue: Decision Logger
Log a decision to the decision log. The decision log is a chronological audit trail of all decisions, from routine operational choices to architectural decisions.
Decision Type Hierarchy
| Type | When to Use | Required Fields | Framework Grounding |
|---|---|---|---|
| OPERATIONAL | Routine choices during task execution | outcome, rationale | WRK domain, Ephemeral, documentable knowledge |
| TACTICAL | Approach changes affecting method | outcome, rationale | WRK domain, Ephemeral-Dynamic, elicitable knowledge |
| DESIGN | Component/schema decisions with rationale | outcome, rationale, context | STR domain, Dynamic-Standing, elicitable with rationale |
| ADR | Cross-reference to Architecture Decision Record | outcome, rationale, context, ref | STR domain, Standing, formal alternatives analysis |
Choosing the Right Type
Did you formally evaluate multiple alternatives with trade-offs?
YES → Use ADR type (create ADR document first, then log with ref)
NO → Continue...
Does this affect how a component or schema works?
YES → Use DESIGN
NO → Continue...
Does this change your approach to the current task?
YES → Use TACTICAL
NO → Use OPERATIONAL
How to Log a Decision
Execute the following bash command:
${CLAUDE_PLUGIN_ROOT}/skills/dialogue-log-decision/scripts/log-decision.sh <type> <actor> <subject> <outcome> <rationale> [context] [tags] [ref]
Required Parameters
| Parameter | Values | Description |
|---|---|---|
type |
OPERATIONAL, TACTICAL, DESIGN, or ADR |
Decision significance level |
actor |
ai:claude or human:<id> |
Who made the decision |
subject |
text | Brief description of what the decision concerns |
outcome |
text | What was decided or done |
rationale |
text | Single-line reasoning (why this choice) |
Conditionally Required Parameters
| Parameter | Required For | Description |
|---|---|---|
context |
DESIGN, ADR | Additional surrounding situation—what led to this decision |
Optional Parameters
| Parameter | Description |
|---|---|
context |
Additional context (optional for OPERATIONAL/TACTICAL) |
tags |
Comma-separated categorisation tags |
ref |
Reference to related document (e.g., ADR-001 for ADR type) |
Examples
OPERATIONAL Decision
${CLAUDE_PLUGIN_ROOT}/skills/dialogue-log-decision/scripts/log-decision.sh OPERATIONAL "ai:claude" "Test failure response" "Added null check to validateInput()" "TypeError indicated undefined parameter" "" "fix,validation"
TACTICAL Decision
${CLAUDE_PLUGIN_ROOT}/skills/dialogue-log-decision/scripts/log-decision.sh TACTICAL "human:pidster" "Refactoring approach" "Refactor auth module before adding feature" "Reduce complexity before extending" "" "refactor,auth"
DESIGN Decision
${CLAUDE_PLUGIN_ROOT}/skills/dialogue-log-decision/scripts/log-decision.sh DESIGN "human:pidster" "Information reference schema approach" "Simplified from URI format to self-describing IDs" "Simpler format reduces cognitive load, maintains backward compatibility" "Initial v1 had complex URI format; user directed simplification" "schema,simplification"
ADR Cross-Reference
${CLAUDE_PLUGIN_ROOT}/skills/dialogue-log-decision/scripts/log-decision.sh ADR "human:pidster" "Graph storage approach" "Created ADR-001 for filesystem-first strategy" "Architectural decision requiring formal alternatives analysis" "Evaluated Kuzu, Neo4j, filesystem options" "architecture,storage" "ADR-001"
Output
The script returns the generated decision ID (e.g., DEC-20260113-143215).
When to Use ADR vs DESIGN
Use DESIGN when:
- You chose an approach but didn't formally document alternatives
- The decision affects a component but not the whole system
- Rationale matters but a full ADR would be overkill
Use ADR when:
- You formally evaluated 2+ alternatives with pros/cons
- The decision has system-wide architectural impact
- You need to document consequences and trade-offs
- Future developers will need to understand why
Process for ADR:
- Create ADR document using
dialogue-create-adrskill - Log cross-reference using this skill with type=ADR and ref=ADR-NNN
Granularity Guidelines
One Decision Per Distinct Choice
Log one decision entry per distinct choice. Do not batch multiple decisions into a single entry.
Why Granularity Matters
- Audit trail: Each decision can be reviewed independently
- Traceability: Specific rationale for each choice is preserved
- Search: Can find all decisions about a specific subject
- Compliance verification: Can count decisions against expected count
When Batching Is Acceptable
Batch only when:
- The decisions are truly identical (same rationale applies to all)
- The items being decided have no individual identity
- Example: "Applied consistent formatting to all 15 files" (one formatting decision, multiple files)
Sharing
Always commit and push immediately after logging a decision. Decisions capture rationale that is otherwise tacit—delayed sharing means delayed theory-building for the team.
git add .dialogue/logs/decisions/ && git commit -m "DEC-YYYYMMDD-HHMMSS: <subject>" && git push