Back to Details

ds-ledger

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ds-ledger

ds-ledger

A long run forgets its own reasons. A short written ledger keeps the goal in view and lets a reviewer trust the result.
长时间运行会忘记自己为何出发。一份简短的书面账本能让目标始终清晰可见，也让审查者信任结果。

Steps

步骤

  1. Create one TSV file, for example 
    .ds-ledger.tsv
    , with the header 
    ts	phase	decision	why	evidence	result
    . Put the goal and done condition in the first row.
  2. Before each step, re-read the goal row and the last ten rows. Check that the next step still serves the goal. If it does not, log the drift and correct course.
  3. After each real decision, append one row:
    • ts: ISO 8601 time.
    • phase: the phase or workstream.
    • decision: what you chose or did, one line.
    • why: the reason in plain words.
    • evidence: a pointer, never prose. A commit hash, 
      file:line
      , a command and its result, or an artifact path.
    • result: the outcome, such as "tests pass", "reverted", "open".
  4. Keep each cell on one line with no tabs.
  5. Log reverts and dropped work too, with the reason. Failures are the most useful rows.
  6. At the end, add a summary row and point the user to the file. Commit it only if a reviewer needs it.
  1. 创建一个 TSV 文件，例如 
    .ds-ledger.tsv
    ，表头为 
    ts\tphase\tdecision\twhy\tevidence\tresult
    。在第一行填入目标和完成条件。
  2. 每一步之前，重新阅读目标行和最后十行。检查下一步是否仍然服务于目标。如果不是，记录这种偏离并纠正方向。
  3. 每次实际决策后，追加一行：
    • ts：ISO 8601 时间。
    • phase：阶段或工作流。
    • decision：你选择或做了什么，用一行写明。
    • why：用平实语言说明原因。
    • evidence：指针，绝不写成段落。可以是 commit hash、
      file:line
      、命令及其结果，或 artifact path。
    • result：结果，例如 "tests pass"、"reverted"、"open"。
  4. 每个单元格保持一行且不含制表符。
  5. 回滚和放弃的工作也要记录，并写明原因。失败记录最有价值。
  6. 最后，添加汇总行，并向用户指出该文件。只有审查者需要时才提交它。

Stop when

停止条件

  • The run ends and the summary row is written.
  • If three rows in a row show no progress toward the goal, stop the run and report.
  • 运行结束且已写入汇总行。
  • 如果连续三行都显示没有朝目标取得进展，则停止运行并报告。

Rules

规则

  • Every row needs evidence you can open or rerun. "Looked fine" is not evidence.
  • Write rows the way you would tell a teammate, plain and concrete.
  • Do not rewrite old rows. Append corrections.
  • 每一行都需要有可打开或重新运行的 evidence。"看起来没问题"不是证据。
  • 像告诉同事那样写各行，直白且具体。
  • 不重写旧行。追加更正内容。