Decision Ledger

Decision Ledger

Purpose

Keep durable project decisions searchable without loading full conversation history. A ledger is project-owned evidence: it records what was proposed, accepted, rejected, or learned from repeatable operational failures.

Use personal memory for long-lived user preferences and conversational context. Use a decision ledger for shared project history that needs paths, status, evidence, and lifecycle.

Activation Boundary

Use this workflow when the task depends on at least one of these:

• a prior project decision or rejected approach;
• a repeated tool, environment, publishing, or validation failure;
• a decision that must be synchronized into a specification;
• an explicit request to record, retrieve, audit, or improve project decision history.

Skip it for routine implementation, one-off troubleshooting with no history signal, generic memory questions, and ordinary skill or tool selection. A ledger lookup should remove uncertainty, not become ceremony on every task.

Core Workflow

1. Extract exact retrieval anchors: project, scope, module, file, symbol, command, error text, symptom, metric, decision status, and user wording.
2. Locate the compact project index, preferring docs/decision-ledger/index.jsonl or the repository's documented equivalent.
3. Search the index before opening note bodies. Use exact keyword and metadata filters first; scripts/ledger_search.py is the dependency-free helper.
4. Open only the best 1-3 notes unless results conflict or the user requests a broad audit.
5. Surface relevant experience and rejected records before recommending a path that may repeat a known failure. Treat proposed records as unverified.
6. State the result:
   • name the matching status and conclusion; or
   • say 未找到相关 ledger 记录 / No relevant ledger record found.
7. When feedback strength matters, score the decision subject—not a person—using reinforcement-policy.md. Treat qualified non-objection as weak R1, explicit adoption as R2, validated success as R3, and durable repeated success as R4; distinguish explicit rejection P1 from evidence-backed errors P2-P4.
8. If the task is discussion-only, stop after reporting the history. Do not edit code, specifications, or ledger records without a requested change.
9. When a decision is implemented and validated, update the full note, compact index, reinforcement evidence, and authoritative specification in the same pass. Rewrite conflicting current guidance; preserve superseded history through links.

Read retrieval-workflow.md when the index is missing, large, multilingual, filtered, or produces conflicting results.

Read record-maintenance.md before creating records, changing status, initializing a ledger, or synchronizing specifications.

Read reinforcement-policy.md before adding or changing reward, penalty, conflict, or hard-block metadata.

Record States

• proposed: discussion or research that is not yet validated.
• accepted: implemented or otherwise verified, with evidence and authoritative-spec alignment.
• rejected: an approach that should not be reused by default, including the failure condition and any reconsideration boundary.
• experience: a repeatable operational lesson with trigger signals, root cause, safe resolution, and validation.

Rank by relevance first. Among similarly relevant results, inspect repeatable experience and rejected guardrails before accepted, then proposed.

Guardrails

• Project-owned records outrank skill-owned examples.
• Verify remembered operational fixes with cheap read-only checks before applying them.
• Never promote model intuition directly into accepted guidance.
• Reinforcement scores affect retrieval and review priority only. They never replace evidence, record status, human authorization, safety policy, or current validation.
• Absence of objection is not proof, consent, or acceptance. It can receive at most provisional R1 after a defined review opportunity.
• No reward can cancel a P4 hard block; conflicting active signals require explicit review.
• Preserve attribution when a user identifies a gap or proposes an improvement.
• Avoid destructive commands copied from historical notes; re-evaluate them against current paths and permissions.
• Keep growing project history outside this skill.

On-Demand References

• Use discussion-memo-template.md for discussion-only conclusions.
• Use accepted-decision-template.md after implementation and validation.
• Use rejected-approach-template.md when an approach should not be repeated by default.
• Use experience-memory-template.md for repeatable operational failures and workflow lessons.
• Read workflow-self-iteration.md only when the user asks to improve this workflow, a validation failure reveals a reusable gap, or a planned review needs current external evidence.
• Read publishing-workflow-experience.md only when maintaining or debugging this skill's public mirror.

Closure Check

Before finalizing substantial ledger work:

1. Confirm that lookup scope stayed compact and the reported status matches the record.
2. Check that rejected or experience guardrails were not missed.
3. For writes, validate frontmatter, index.jsonl, referenced paths, evidence, reinforcement aggregates, and authoritative-spec consistency.
4. Report what changed, what evidence supports it, and what remains proposed or out of scope.