Back to Details

addon-decision-justification-ledger

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add-on: Decision Justification Ledger

附加组件：决策理由台账

Use this skill when decision visibility is required by default and no non-trivial change should ship without a recorded rationale.
当默认要求决策可追溯、所有非 trivial 变更都必须附带记录的理由才能上线时，使用此技能。

Compatibility

兼容性

  • Works with all 
    architect-*
    , 
    addon-*
    , and 
    ui-*
    skills.
  • Required default for 
    production-default
    mode.
  • 兼容所有 
    architect-*
    、
    addon-*
    和 
    ui-*
    类技能。
  • 是 
    production-default
    模式的默认必选组件。

Inputs

输入项

Collect:
  • DECISION_LOG_LEVEL
    : 
    standard
    | 
    strict
    (default 
    strict
    ).
  • DECISION_SCOPE
    : 
    architecture-only
    | 
    architecture+implementation
    (default 
    architecture+implementation
    ).
  • DECISION_LOG_PATH
    : default 
    docs/DECISION_LOG.md
    .
  • DECISION_TRACE_PATH
    : default 
    REVIEW_BUNDLE/DECISION_TRACE.md
    .
收集以下参数：
  • DECISION_LOG_LEVEL
    ：
    standard
    | 
    strict
    （默认 
    strict
    ）。
  • DECISION_SCOPE
    ：
    architecture-only
    | 
    architecture+implementation
    （默认 
    architecture+implementation
    ）。
  • DECISION_LOG_PATH
    ：默认 
    docs/DECISION_LOG.md
    。
  • DECISION_TRACE_PATH
    ：默认 
    REVIEW_BUNDLE/DECISION_TRACE.md
    。

Integration Workflow

集成工作流

  1. Add decision visibility artifacts:
text
docs/DECISION_LOG.md
REVIEW_BUNDLE/DECISION_TRACE.md
  1. Record each non-trivial decision in 
    docs/DECISION_LOG.md
    :
  • Decision ID
  • Context and requirement
  • Options considered
  • Chosen option
  • Concrete justification
  • Tradeoffs and residual risks
  • Validation evidence
  1. Link changed files to decision IDs in 
    REVIEW_BUNDLE/DECISION_TRACE.md
    so reviewers can map code to rationale quickly.
  2. Keep entries append-only for auditability; corrections should be new entries that reference previous IDs.
  1. 添加决策可追溯工件：
text
docs/DECISION_LOG.md
REVIEW_BUNDLE/DECISION_TRACE.md
  1. 在 
    docs/DECISION_LOG.md
    中记录每一项非 trivial 决策：
  • 决策 ID
  • 上下文与需求
  • 考虑过的可选方案
  • 最终选择的方案
  • 具体理由
  • 权衡取舍与遗留风险
  • 验证证据
  1. 在 
    REVIEW_BUNDLE/DECISION_TRACE.md
    中将变更文件与决策 ID 关联，方便评审人员快速将代码对应到决策理由。
  2. 条目仅支持追加以保证可审计性；修正内容应为引用旧 ID 的新条目。

Required Template

所需模板

docs/DECISION_LOG.md

docs/DECISION_LOG.md

markdown
undefined
markdown
undefined

Decision Log

Decision Log

DEC-001 <short title>

DEC-001 <short title>

  • Context: <what requirement or constraint triggered this>
  • Options: <A>, <B>, <C>
  • Chosen: <selected option>
  • Justification: <why this option is best for this case>
  • Tradeoffs: <known downsides>
  • Risks: <residual risk + mitigations>
  • Evidence: <tests/build/checks/docs>
undefined
  • Context: <what requirement or constraint triggered this>
  • Options: <A>, <B>, <C>
  • Chosen: <selected option>
  • Justification: <why this option is best for this case>
  • Tradeoffs: <known downsides>
  • Risks: <residual risk + mitigations>
  • Evidence: <tests/build/checks/docs>
undefined

REVIEW_BUNDLE/DECISION_TRACE.md

REVIEW_BUNDLE/DECISION_TRACE.md

markdown
undefined
markdown
undefined

Decision Trace

Decision Trace

FileDecision IDSummary
src/app/main.pyDEC-001Chose local lexical index for offline deterministic retrieval
undefined
FileDecision IDSummary
src/app/main.pyDEC-001Chose local lexical index for offline deterministic retrieval
undefined

Guardrails

防护规则

  • Documentation contract for generated code:
    • Python: write module docstrings and docstrings for public classes, methods, and functions.
    • Next.js/TypeScript: write JSDoc for exported components, hooks, utilities, and route handlers.
    • Add concise rationale comments only for non-obvious logic, invariants, or safety constraints.
    • Apply this contract even when using template snippets below; expand templates as needed.
  • No non-trivial decision without rationale.
  • Do not use generic claims like "best practice" as a sole justification.
  • If alternatives were not considered, explicitly state why only one path is viable.
  • Missing decision entries are merge blockers in production-default mode.
  • 生成代码的文档约定：
    • Python：为模块、公共类、方法和函数编写文档字符串。
    • Next.js/TypeScript：为导出的组件、hooks、工具函数和路由处理函数编写 JSDoc。
    • 仅为非显而易见的逻辑、不变量或安全约束添加简洁的理由注释。
    • 即使使用下方的模板片段也需遵守本约定，可按需扩展模板。
  • 任何非 trivial 决策都必须附带理由。
  • 不得将“最佳实践”这类泛泛的说法作为唯一理由。
  • 如果未考虑替代方案，需明确说明为何只有一条路径可行。
  • 在 production-default 模式下，缺失决策条目会成为合并阻塞项。

Validation Checklist

验证检查清单

  • Confirm generated code includes required docstrings/JSDoc and rationale comments for non-obvious logic.
bash
test -f docs/DECISION_LOG.md
test -f REVIEW_BUNDLE/DECISION_TRACE.md
rg -n "## DEC-[0-9]{3}" docs/DECISION_LOG.md
rg -n "Justification:|Tradeoffs:|Risks:" docs/DECISION_LOG.md
  • 确认生成的代码包含要求的文档字符串/JSDoc，且为非显而易见的逻辑添加了理由注释。
bash
test -f docs/DECISION_LOG.md
test -f REVIEW_BUNDLE/DECISION_TRACE.md
rg -n "## DEC-[0-9]{3}" docs/DECISION_LOG.md
rg -n "Justification:|Tradeoffs:|Risks:" docs/DECISION_LOG.md

Decision Justification Rule

决策理由规则

  • Every non-trivial decision must include a concrete justification.
  • Capture the alternatives considered and why they were rejected.
  • State tradeoffs and residual risks for the chosen option.
  • If justification is missing, treat the task as incomplete and surface it as a blocker.
  • 所有非 trivial 决策都必须包含具体理由。
  • 记录考虑过的替代方案以及被否决的原因。
  • 说明所选方案的权衡取舍与遗留风险。
  • 如果缺失理由，视为任务未完成，并标记为阻塞项。