Whyfile: every decision, with the reason it was made

Technical debt often starts with forgotten context. When a developer asks why a specific database or architecture was chosen six months ago, the answer is usually buried in a slack thread or lost in a previous session. This skill maintains an append-only log of non-obvious technical choices, ensuring every trade-off is documented with its rejected alternatives and rationale.

What it does

• Captures context by documenting the specific situation that forced a technical choice.
• Documents rejected options to prevent the team from repeating experiments that already failed.
• Records rationales based on facts, benchmarks, and constraints rather than opinions.
• Tracks reversals using new entries instead of editing history, maintaining a clear audit trail.
• Surfaces history by searching the log to answer "why did we choose X?" with full context.

How it works

1. Log a decision by providing the chosen option, the rejected alternatives, and the specific trade-off made.
2. Query the log by asking about a specific tool or feature to retrieve its historical entry.
3. Reverse a choice by creating a new entry that links to the original, documenting what new information changed the plan.

Frameworks & tools

This skill works with any repository structure. It defaults to docs/decisions.md but automatically detects and uses existing patterns like DECISIONS.md or docs/adr/.

Why this beats prompting it yourself

Manual prompting often misses the "Rejected" field, which is the most important part of avoiding future circular debates. This skill enforces a strict schema and append-only logic that keeps the agent from overwriting past project history.

Use cases

• Documenting the choice of a specific library over a popular alternative.
• Recording architecture decisions made during a design session.
• Explaining to a new contributor why a specific "obvious" solution was avoided.
• Logging the reversal of a previous decision when new constraints emerge.

Known limitations

Focuses only on non-obvious technical trade-offs. It will skip trivial choices like code formatting or standard library usage.