agentleFS
netanelavrnetanelavr/dotcursor/skills/kit-decisions/SKILL.md

kit-decisions

Skill6 starsChanged 27 days agoMITView on GitHub

Keep a short living decision log for one large feature. Use while building it, before continuing the work, or when a reviewer needs the history.

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep one short file for a large feature so a later agent can see why the code looks like this.

    line 9
  2. Very specific:

    Not the pre-code concept log (kit-plan).

    line 20
  3. Very specific:

    Not a glossary or sparse ADRs (kit-challenge-design).

    line 21
  4. Very specific:

    Not a reusable rule after a repeated miss (kit-capture-lesson).

    line 22
  5. Very specific:

    Not a review of the diff (kit-review).

    line 23
  6. Very specific:

    If a decisions.md for this feature already exists, use that path.

    line 29
  7. Distinctive:

    Create the file only when the first real entry exists.

    line 33
  8. Distinctive:

    When an accepted decision is replaced, move the old bullet to Rejected and add the new evidence.

    line 48
  9. Distinctive:

    Leave a heading in place when its section is empty.

    line 70
  10. Distinctive:

    Update the matching section in place.

    line 78
  11. Very specific:

    If an Accepted item is hard to reverse, surprising without this file, and had a real alternative, offer an ADR through kit-challenge-design.

    line 79

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Decisions

Keep one short file for a large feature so a later agent can see why the code looks like this.

Two jobs:

  • Capture — record a closed fork or a landmine
  • Brief — read the file before review or more work on that feature

Accept kit-decisions capture|brief. If omitted: capture when this conversation closed a fork or hit a landmine; brief when they ask what was already decided, or before changing the feature.

What this is NOT

  • Not the pre-code concept log (kit-plan). That log lives in chat and stops at approval.
  • Not a glossary or sparse ADRs (kit-challenge-design). Promote only when the ADR bar is met.
  • Not a reusable rule after a repeated miss (kit-capture-lesson).
  • Not a review of the diff (kit-review). Brief states what the log says. Review still owns findings.

Where the file lives

Default: docs/features/<feature>/decisions.md

If a decisions.md for this feature already exists, use that path. Do not move it.

The file stays as long as the feature lives. Do not delete it on merge.

Create the file only when the first real entry exists.

What to record

Four sections. One short bullet each. Edit in place. No chat transcript.

SectionWrite when
AcceptedA direction was chosen. Include why, and what must not be undone without new evidence.
RejectedA direction was tried or seriously considered, and lost. Include why, and when it may be revisited.
LandminesSomething looked trivial and broke, or a small change would undo a hard-won fix.
OpenA real fork is still undecided.

Skip obvious choices, easy-to-reverse trivia, and glossary terms.

When an accepted decision is replaced, move the old bullet to Rejected and add the new evidence. Keep the original why.

Format

# Decisions: {feature}

Living log for this feature. Hard-to-reverse decisions that meet the ADR bar belong in `docs/adr/` — leave a pointer here.

## Accepted
- **{decision}** — {why}. Do not undo without {new evidence}.

## Rejected
- **{option}** — {why it lost}. Revisit only if {condition}.

## Landmines
- **{looks trivial}** — {what broke, and why the obvious fix fails}.

## Open
- **{fork}** — {what is still unknown}.

Leave a heading in place when its section is empty.

Flow

Capture

  1. Name the feature. Find the file, or create it at the default path on the first entry.
  2. Distill this conversation into one or two bullets. Do not paste the transcript.
  3. Update the matching section in place. Move Open items when they close.
  4. If an Accepted item is hard to reverse, surprising without this file, and had a real alternative, offer an ADR through kit-challenge-design. Write the ADR only after they say yes. Then add a one-line pointer under Accepted.
  5. Show the bullets that changed. Stop.

Brief

  1. Find the file. If it is missing, say so. Do not invent history.
  2. List only the bullets this change can touch.
  3. Before review: re-proposing a Rejected option needs new evidence that beats the recorded why. Undoing an Accepted decision without that evidence is a finding for kit-review.
  4. Before more work: state the landmines and accepted constraints the edit can hit. Continue only if the change respects them, or the user accepts the new evidence.

Do / Don't

DoDon't
"Rejected sync retry — duplicates under timeout. Revisit only with an idempotency key."A paragraph retelling the thread
One bullet when a fork closesAn entry after every message
A pointer to ADR-0007 after they accept the promotionA copy of the whole ADR in this file
"No decisions.md for billing. Nothing recorded."A guessed history

Generic only: no employer names, private hosts, or work-only tools.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.