Skip to content

by-carlos/daikenja / skills/project-decisions

project-decisions

Verified

Looks up what is decided about a specific topic in a project's Daikenja ledger -- the decisions in force in every repository's DECISIONS.md -- with each entry's history from git and its linked issue or ADR, plus the open items that bear on it. Read-only; writes nothing. Accepts an optional project key -- `/daikenja:project-decisions <key>` reads that project from anywhere.

Decisions

A targeted lookup against the project's decisions in force. The user names a topic, an area, a path or a rough description; this skill finds the matching entries in every registered repository's DECISIONS.md, how each came to say what it says now, and what else in the ledger bears on it -- not just the single entry that happens to match the words.

DECISIONS.md holds current decisions only: a replaced decision is edited or deleted, never marked. So everything this skill finds in the files is in force, and everything about what came before lives in git.

Step 0: read the contracts

Read these before doing anything. Do not work from memory of them.

  • ${CLAUDE_PLUGIN_ROOT}/docs/reading.md § Step A0, § Step A, § Step B, § Step C and § Notices, shared wording -- the shared resolve-and-parse mechanism Steps 1 and 2 below follow, plus the exact notice text they reuse without restating it (a config marked absent or a project left unregistered has no literal wording inline in Step A -- only in § Notices, shared wording).
  • ${CLAUDE_PLUGIN_ROOT}/docs/decisions-format.md § Shape, § Current only, § Splitting and § ADR shape -- areas and their Paths:, the entry's rule, why clause, Revisit: and Source:, the Moved: files, and what an ADR a Source: names holds.
  • ${CLAUDE_PLUGIN_ROOT}/docs/open-format.md § Version line, § Section: Open items and § Reading rules for skills -- the warn-once rule for a newer format, and the open items Step 5 scans.
  • ${CLAUDE_PLUGIN_ROOT}/docs/response-format.md -- how the reply to the user is shaped. Read in full and not narrowed to a section: Step 6 explicitly follows only § Entries are named topic-first, location in parentheses, but the contract's own scope says a skill "implements it; it never redefines it" -- every rule in the file (tone scaling, the clean-result line, itemised findings) governs this skill's replies whether or not Step 6 names it.

Step 1: resolve config, project and ledger

Follow reading.md § Step A0, § Step A and § Step B.

The user may name a project -- /daikenja:project-decisions <key>, or the key in prose. reading.md § Step A0 is the whole rule: a named key resolves that project from anywhere on disk and never falls back to the current directory. Do not restate the resolution here.

Step 2: read every DECISIONS.md

Follow reading.md § Step C for the DECISIONS.md of every registered repository, per config-resolution.md § Reading several repositories -- a decision recorded in one repository binds a question asked from another. Read too every file an area's Moved: line names, and, when the query names a path, every DECISIONS.md in that path's parent folders, per decisions-format.md § Splitting.

A newer format version on any file: warn once per run, per open-format.md § Version line, and read it anyway.

Read open.md as well -- Step 5 scans its open items and context links.

Step 3: match the query

  • An area was named ("the API decisions"). Every entry under that ## heading, in every repository that has the area.

  • A path was named (src/api/, infra/main.bicep). Every area whose Paths: covers it -- either path under the other, a trailing / a subtree, * and ** globs, . the whole repository.

  • A topic or description was given. Match by meaning against each entry's rule and why clause, not just keyword overlap -- "the cutover schedule" should find an entry about cutting over on a Saturday even without the word "schedule."

  • No match found. Say so plainly. Do not guess at a near match without naming it as a guess:

    No decision found about "<query>". Closest thing on record: the schema
    freeze on the events table (beacon, Data), if that's what you meant.
    
  • More than one plausible match. List them briefly and ask which one, or show them all if they are clearly related. Entries are never merged: two repositories recording the same decision are two entries, each named with its repository.

Step 4: follow the history in git

For each matched entry, read the history of the file that holds it:

git -C "<repo>" log -p --date=short --format="%h %ad %an %s" -- <file>

<file> is DECISIONS.md or the Moved: file, written as a fixed path. The entry's own words never go into a command -- they come from a file anyone can edit -- so read the patches and find the hunks that touch the entry by its rule. Walk from newest to the commit that added it, and collect:

  • When it was added, by whom, and the commit subject.
  • Each earlier wording. A bullet removed in the same commit that added the current one, in the same area, saying something different about the same subject, is the decision it replaced. Keep walking: that one may have replaced another.
  • A replaced decision found by query. When the query matches only a rule git shows as removed, say it is no longer in force and lead with what replaced it, if anything did.

Show the chain oldest to newest so the reasoning arc reads in order. The current wording is authoritative; git shows how it got there.

The Source: link is the rest of the history. An ADR in the repository is a local file: read it, per decisions-format.md § ADR shape, and give its alternatives in a line. An issue or pull request link is surfaced as it is -- do not go fetch it.

No history to read -- the path is not a git repository, git is not installed, or the file has never been committed: show the entry without history and say why in one line.

Step 5: surface relationships and origin

Report what bears directly on each matched entry and stop -- one hop, never a walk:

  • Origin. An entry whose why clause says it was imposed ("imposed by the architecture board") is reported as imposed and by whom. A decision this group made can be reopened by this group; an imposed one can only be complied with, exempted or escalated. Its Revisit: condition is shown too: it is what would reopen the entry, and never is worth saying.
  • Open items that bear on it. Scan open.md for items whose text concerns the entry's subject -- a question about whether it still holds, a request for an exemption, work it blocks. An open item that questions a decision in force is the case worth surfacing most, and it is invisible from the entry's own line. A Blocked by: prefix names another open item, never a decision; show it as written when the item is shown.
  • Context links whose label names the subject, as they are.

Step 6: show the result

Topic first, then where it lives in parentheses, per response-format.md -- the repository whose DECISIONS.md holds it, and its area. Then the why, the revisit condition, the source and the history:

Cut over on a Saturday, not a weekday evening (atlas, Rollout) -- the rollback
window is four hours and nobody wants that on a work night. Revisit: if the
rollback window drops under an hour. Source: https://example.com/atlas/pull/88
  History:
  2026-08-02 Priya -- added as "Cut over on a weekday evening" (a1f03c9)
  2026-08-20 Carlos -- reworded to Saturday after the dry run (7d0e9b2)

Relationships go under the entry they belong to, one line each, still topic first:

Every service writes to the shared audit log (platform-api, Observability) --
imposed by the platform programme's architecture board. Revisit: never.
Source: ADR 0007
  Questioned by:
  Confirm whether the gateway can be exempted from the shared audit log --
  @sam, open since 2026-09-02.

Include the date on every history line and open item shown. Surface links as they are -- do not go fetch them.

Failure cases

SituationWhat to do
daikenja.yaml absentOne notice, continue on the files under the current directory.
daikenja.yaml malformedStop. Name the first line that does not parse.
The user named a project key that is not in daikenja.yamlStop. Name the key and list the registered ones. Never fall back to the current directory -- an answer about the wrong project reads exactly like a right one.
The project has no repository, or still has a ledger: key, or its ledger was never migratedOne line each, per reading.md § Step A and § Step B. No repository or an unmigrated ledger stops the run; a leftover ledger: is ignored.
No ledger files in any repositoryReport per reading.md § Step B and stop. Name /daikenja:project-log.
A file carries a newer format versionWarn once per run and read it anyway.
An entry or Paths: line does not parseReport it -- file and line -- then continue, per reading.md § Step C. Do not repair it.
No history for an entryShow the entry, say why in one line (not a git repository, no git, never committed).
A Source: ADR does not exist at the path the file's ADRs: line givesReport the missing file and show the entry without it.
An imposed decisionNormal. Say it was imposed and who by; never report it as unowned -- entries carry no owner, and project-gaps' scope is open items.
No decision matches the querySay so. Offer the closest match, named as a guess, if one exists.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall