More screenshots

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Whyfile: every decision, with the reason it was made

    1

    Keeps an append-only log of non-obvious choices: context, decision, rejected options and why. Answers "why did we choose X?" straight from the log.

    Free

    1 useSecurity scanned
    Whyfile: every decision, with the reason it was made

    Whyfile: every decision, with the reason it was made

    Example session with this skill installed

    We decided to use SQLite for the local cache instead of Redis. It's simpler for this scale and we don't need the networking overhead. Log this.

    • Read your context and instructions
    • Compiled the whyfile

    I have recorded the decision to use SQLite for the local cache in docs/decisions.md.

    2024-05-22: SQLite for local cache instead of Redis

    Context: The application requires a local persistence layer for session data; the current scale does not justify a separate service.
    Decision: Use SQLite as the local caching engine.
    Rejected: Redis (adds infrastructure complexity and networking overhead for a single-node setup).
    Rationale: SQLite provides zero-config persistence, sufficient performance for the current load, and keeps the deployment footprint small.
    Revisit if: The system needs to scale horizontally or requires distributed cache invalidation.

    Logged: SQLite for local cache instead of Redis

    Next steps

    1. Review the entry in docs/decisions.md to ensure the rationale matches your intent.
    2. Link this decision in the upcoming PR description for the cache implementation.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    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.

    Only logs non-obvious technical trade-offs. Requires an existing or new markdown file in the repository. Does not support multi-file logs; uses a single append-only file.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    1 use

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 29 days ago

    • Free with an Agensi account

    Permissions

    Write Files
    Listed29 days ago

    What's inside

    Frequently Asked Questions

    Keeps an append-only log of non-obvious choices: context, decision, rejected options and why. Answers "why did we choose X?" straight from the log.

    This skill uses the open SKILL.md standard. Use it through an MCP-compatible agent connected to Agensi, and check the compatibility information on this page for confirmed agents and required capabilities.

    Connect your AI agent to Agensi through MCP, then ask it to use Whyfile: every decision, with the reason it was made on your task. Your agent loads the latest approved version each time. Paid skills require a purchase or active subscription. Skill files are not available for download; your licence does not allow you to save, copy or export any part of a skill.

    New in Technical Documentation