history-hygiene

Record final confirmed outcomes to history.md, replacing reversed decisions.

Updated Aug 27, 2026

Search Tags:#decision #history #integrity #log #version-control #record-keeping

Ready to run

npx skills add https://github.com/CarlosSardo/nats-poc-simulator --skill history-hygiene-carlossardo

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: history-hygiene
Source: https://github.com/CarlosSardo/nats-poc-simulator/tree/main/.copilot/skills/history-hygiene
Command: npx skills add https://github.com/CarlosSardo/nats-poc-simulator --skill history-hygiene-carlossardo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake.

Core Features & Use Cases

Record the final outcome to history.md, not intermediate states.
Update history on reversals to reflect the true current decision.
One truth principle: future agents should not need to cross-reference multiple files.

Quick Start

Log only the final decision to history.md after confirmation.

Frequently Asked Questions about history-hygiene

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I keep decision history logs accurate when outcomes are reversed?▼

To keep decision history logs accurate when outcomes are reversed, update history.md by replacing earlier entries with the final confirmed decision. This ensures future agents read the true current outcome instead of stale intermediate states.

Why does stale decision history poison downstream agent workflows?▼

Stale decision history poisons downstream agent workflows because future agents read these logs cold and assume they reflect truth. If intermediate requests or reversed decisions remain, agents repeat mistakes based on incorrect past outcomes.

What is the best way to record final outcomes in markdown history files?▼

The best way to record final outcomes in markdown history files is to log only the confirmed final decision. Wait until confirmation before updating history.md, ensuring the file reflects one single truth rather than iterative states.

Do I need to cross-reference multiple files to track version-control decisions?▼

You do not need to cross-reference multiple files to track version-control decisions if history.md is updated on reversals. Replacing earlier entries with the true current decision maintains a single source of truth for future readers.

When should I not use intermediate state logging for record-keeping?▼

You should not use intermediate state logging for record-keeping when iterations or reversals occur in a decision workflow. Logging unconfirmed requests risks leaving incorrect entries that mislead future agents reading the history cold.