history-hygiene
Record final outcomes to history.md, not intermediate requests or reversed decisions
Best use case
history-hygiene is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Record final outcomes to history.md, not intermediate requests or reversed decisions
Teams using history-hygiene should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/history-hygiene/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How history-hygiene Compares
| Feature / Agent | history-hygiene | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Record final outcomes to history.md, not intermediate requests or reversed decisions
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
## Context 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. ## Patterns - **Record the final outcome**, not the initial request. - **Wait for confirmation** before writing to history — don't log intermediate states. - **If a decision reverses**, update the entry immediately — don't leave stale data. - **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened. ## Examples ✓ **Correct:** - "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)" - "Reverted to Node 18 per Brady's explicit request on 2024-01-15" ✗ **Incorrect:** - "Brady directed v0.6.0" (when later reversed) - Recording what was *requested* instead of what *actually happened* - Logging entries before outcome is confirmed ## Anti-Patterns - Writing intermediate or "for now" states to disk - Attributing decisions without confirming final direction - Treating history like a draft — history is the source of truth - Assuming readers will cross-reference or verify; they won't
Related Skills
{skill-name}
{what this skill teaches agents}
xunit-v3-discovery
Fix xUnit v3 test projects that compile but show zero discovered tests under dotnet test.
result-web-feedback
Apply Result<T>-based feedback patterns in Razor Pages and HTMX flows.
result-foundation
Add or extend MoreSpeakers Domain Result types with explicit factory methods and structured errors.
reflection-contract-tests
Use reflection-based tests to lock an API contract before the implementation lands.
windows-compatibility
Cross-platform path handling and command patterns
test-discipline
Update tests when changing APIs — no exceptions
squad-conventions
Core conventions and patterns used in the Squad codebase
session-recovery
Find and resume interrupted Copilot CLI sessions using session_store queries
secret-handling
Never read .env files or write secrets to .squad/ committed files
release-process
Step-by-step release checklist for Squad — prevents v0.8.22-style disasters
project-conventions
Core conventions and patterns for this codebase