by-carlos/daikenja / skills/project-log
project-log
VerifiedRecords decisions, open items and sources in a project's ledger. Use when the user says "log this", "record this decision", "add this to the ledger", or asks for what was settled to be written down.
Log
The ledger is the project's memory: DECISIONS.md, the decisions still in
force, at the root of each registered repository, and .daikenja/open.md, what
is still unsettled, in the home repository. Git is the history. This skill is
the only thing that writes either file.
Hard rules
Never write lines the user has not stated or approved. For interpreted material -- threads, pastes, transcripts, anything this skill classifies -- show the exact lines first, as one batch, wait for the user to say yes, then write. "Yes" means the user said so in this conversation, and an approval of one batch does not carry to the next one. For a fact the user dictated (Step 5's same-turn path), the dictation is the approval, given in advance -- and it stays valid only while the written lines add nothing the user did not say.
Never invent an entry. Everything written comes from the material the user gave you. If something is implied but not said, put it in the proposal as a question, not as an entry.
Never repair a broken file on your own initiative. Report the problem, name the line, and stop. Repair is a separate write and needs its own approval.
Never commit. This skill changes the files in the working tree and stops
there. The user commits them with the work they belong to; project-catchup
lists them as not committed yet until then.
Never write either file from any other skill. Another skill that needs an
entry -- meeting-review, setup-project's seed, the migration in
docs/ledger-migration.md -- hands its entries to this one, and they go
through Step 2 to Step 8 like any other batch: the refusals, the repository
question and the duplicate check apply to them too. That is a
project-log via <skill> run.
Step 0: read the contracts
Read these before writing anything. They are binding, and they are the only place their detail lives. Do not work from memory of them.
${CLAUDE_PLUGIN_ROOT}/docs/decisions-format.md-- theDECISIONS.mdformat: what gets kept, areas andPaths:, the entry shape, current-only.${CLAUDE_PLUGIN_ROOT}/docs/open-format.md-- theopen.mdgrammar, theBlocked by:prefix, closing an item, and the version rule for both files.${CLAUDE_PLUGIN_ROOT}/docs/config-resolution.md-- where the config lives, how a project and its files are resolved, and the legacy keys.${CLAUDE_PLUGIN_ROOT}/docs/config-versioning.md-- the version-marker notice this skill emits and never migrates.${CLAUDE_PLUGIN_ROOT}/docs/response-format.md-- how the reply is shaped. Proposed lines stay in file grammar; the talk around them follows this.
Two more, read only when the run needs them:
${CLAUDE_PLUGIN_ROOT}/docs/config-drive.md, for adrive:pointer. Step 5's owner check is the only thing here that readspersonas.md.${CLAUDE_PLUGIN_ROOT}/docs/project-log-reference.md, this skill's branch-only sections. Every rule there binds exactly as if it sat here, and each step below names its section at the moment that branch opens.
If they ever disagree with this skill, the contract wins and you say so.
Step 1: get the material
- A link was given. Fetch it with whatever tool is connected. Get the whole thread, not the preview.
- Text was pasted. Use it as-is. Do not go looking for more.
- A plain description was given ("log that we picked Postgres"). That is enough material.
- Nothing was given. Ask what to log. Do not search for it, and do not read the repository to guess what happened.
- Entries handed over by another skill. Use them as that skill classified them. They were classified, not dictated.
If a fetch fails, say what failed in one line and ask for a paste. Never guess at the content of something you could not read.
Step 2: resolve the config, the project and the files
Follow config-resolution.md § Resolution order exactly. The migration's own
batch skips this resolution: it names its targets by absolute path, so item
2's no-paths stop and item 4's paths: [] and unmigrated-ledger refusals do
not apply to it (project-log-reference.md § A batch handed over by another
skill). Every other run, setup-project's seed included, resolves in short:
-
Read
~/.claude/daikenja/daikenja.yaml. Absent is not fatal -- this skill works on defaults. Malformed YAML is fatal: report the first line that does not parse and stop. -
A project key was named. Match it per
config-resolution.md§ By key. No match: say so, list the registered keys, stop. A match with no paths: item 4's "needs migration" line, and stop. Any other match: use it, from any directory -- item 3 places every file from the entry alone. Never fall back to directory matching -- a named key is decisive. No key was named: match the current directory against every path of every entry, longest prefix wins. -
Resolve the files per
config-resolution.md§ FindingDECISIONS.mdandopen.md:DECISIONS.mdat the root of every path in the entry, and.daikenja/open.mdin the home repository, which is the first path. No match: the current directory is the one root. -
Apply
config-resolution.md§ Legacy keys and unmigrated ledgers. A leftoverledger:key gets its one line and the run continues. Apaths: []entry is "needs migration": its line, and stop. An old ledger at<home>/.daikenja/ledger.mdwith noopen.mdbeside it is refused -- whether or not aDECISIONS.mdexists. Write that line, write nothing, and scaffold nothing:The ledger at <home>/.daikenja/ledger.md needs migration -- run /daikenja:setup-user. -
Emit the version-marker notice if it applies, per
config-versioning.md. It never blocks a write, and this skill never migrates anything.
A file on disk wins over the config. If DECISIONS.md or
.daikenja/open.md exists under the current directory but no project matches,
use it. Then say so in one line and name the skill that registers it -- you do
not write daikenja.yaml yourself:
This project is not in daikenja.yaml. The ledger still works. To register it,
run /daikenja:setup-project -- it adds the entry for this directory.
Step 3: scaffold the ledger when it is missing
Only for a file the batch writes to that does not exist yet. Read
project-log-reference.md § Step 3: scaffold the ledger when it is missing and
follow it -- it owns the refusals, the is-this-a-project check, the copy from
the template, and how the scaffold folds into the Step 5 approval.
A DECISIONS.md that exists is adopted, whoever wrote it -- another
plugin, a person, an earlier run. New entries go into it. It is never
overwritten, re-scaffolded or reformatted.
Step 4: read what is already there
Read every file the batch could touch before proposing anything.
The version lines first, per open-format.md § Version line. A newer
version than this plugin knows, in any file the batch would write, refuses the
whole batch -- nothing is written to any file, not even the entries for the
others.
Name the file and the version, ask for a plugin update, and stop:
<file> was written by a newer format (version <n>); update the Daikenja plugin
before logging. Nothing was written. The version rule is in
${CLAUDE_PLUGIN_ROOT}/docs/open-format.md.
A file with no version line is read as version 1, and the proposal adds the line.
The sections. In open.md, locate each of the three H2 headings by exact
name; a missing one stops the run per project-log-reference.md § Failure
cases. In each DECISIONS.md, read the areas and their Paths: lines.
The existing entries. You are checking whether what the user is logging is already recorded. Compare by meaning, not by wording. Nothing carries an ID: a decision is found by its area and its words, an open item by its words.
Step 5: build the proposal
The same-turn path for dictated facts
When the material is a fact the user dictated, skip the proposal: write immediately, then show the exact written lines verbatim, under the file they went to. The dictation is the approval of that batch. A correction afterwards ("change the owner to @sam") is an ordinary edit, and the uncommitted change is there in the diff for the user to see.
A run takes this path only when all four of these hold. Fail any one and the run follows propose-then-wait below.
- The material is the user's own statement, typed as the request itself. A link, a paste or a transcript never qualifies, even when the user wrote parts of it.
- The user's phrasing settles the classification. The user names the kind ("log the decision that...", "add an open item...") or the statement classifies without judgement.
- Every field resolves without a question. For an open item: the date is
today or an exact date the user gave, the owner is who the user named, the
user for their own call, else
@unassigned. For a decision: the rule, the why and the revisit condition are all in the user's words, and the repository and area follow without judgement (below). An approximate date drops the run. So does a decision with no stated why or revisit condition -- asking for it is a question. - The operation is byte-determined. New entries, and changes the user
names exactly ("close the item about the alert thresholds"). The duplicate
check still runs first: a hit the user did not name drops the run. At most
about three entries -- more is a batch to propose. A
Blocked by:prefix counts only when the user stated the block and named an item that is in the file.
Scaffolding a missing file, repairs, and every project-log via <skill> run
never take this path.
Classify before you write
Getting this wrong pollutes the ledger, and the ledger is what every other skill reads.
- A decision is something settled: someone with standing said it, or the
group converged and nobody objected. It goes to a
DECISIONS.md. - An open item is a named thing that is not settled: a question, a task
with no owner or no answer, a dependency. It goes to
open.md. - A suggestion nobody agreed to is neither. Leave it out, or raise it as an open item if it is a real unanswered question. A question or a proposal is not a decision.
- A document to track is a source; a useful address is a context link.
Both go to
open.md. When the material does not say which, ask. Readproject-log-reference.md§ Record a source when the run records one.
Apply the keep rule to every decision drawn from interpreted material, per
decisions-format.md § What gets kept. One that meets none of its three tests
goes in the proposal under "Not kept", with the reason, and is written only if
the user asks for it. A decision the user dictated was kept by the user.
Two branches open here, each in project-log-reference.md:
- A decision made outside this group that binds it -- a published standard, a policy, a contract term. Read § Mark a decision that was imposed.
- The material states that one open item blocks another. Read § Record a relationship only where the source says so.
When you cannot tell, ask -- but never serially. Collect every clarifying question the run needs and ask them all in one round, one line each, in the proposal's "Questions before I write" block. A question the user answered, or that the material or config already answers, is never asked again in the run. One follow-up is allowed only when the user's own answer created a new ambiguity, and it names that answer as the cause. Do not resolve an ambiguity yourself and do not log both readings.
Place each decision
Which repository. A single-repository project has one DECISIONS.md. In a
multi-repository project, a decision goes to the repository whose code it
constrains, and a project-wide one -- scope, commitments, people -- to the
home repository. When the decision's paths do not say which, ask which
repository's DECISIONS.md it belongs in. Never guess and never write it to
two.
Which area. Use the area whose Paths: covers what the decision
constrains. When none does, propose a new area with its heading and Paths:
line, per decisions-format.md § Shape. When two could, ask.
The entry is the shared shape, with its em dash: **<rule now in force>** — <why>. Revisit: <condition, or "never">. Source: <link, issue, pull request or thread>. State the rule, not its history. A why or revisit condition the
material does not give is a question, never filled in. Source: names the
link, issue or thread the material came from, and is left out when it has
none -- never invented.
Attribute correctly
Only open items carry an owner. DECISIONS.md entries have none. The owner is
@ plus one token, no spaces, lowercase.
- A person named in the material owns the item (
@priya). - The user owns what the user says is theirs: the first token of
profile.namefrom the config. - Nobody identifiable means
@unassigned. Write it out; never leave the field empty. An unowned item is whatproject-gapsreports.
Never merge two people's positions into one entry.
Say when a handle is new
A handle is free text, so one colleague can pick up several spellings. This check surfaces the second spelling as it arrives, when fixing it costs one word. It is a notice, not a gate.
Run it after the duplicate check, over every owner the batch writes: a new
item's, and an owner changed by an edit. Skip @unassigned. It does not audit
what is already in the file.
- Look in
open.mdfirst. A handle that already owns an item there is known. Say nothing. This is the common case, and whypersonas.mdis usually never read. - Otherwise resolve
profile.personas, perconfig-resolution.md§ Resolvingwriting_styleandpersonas. The handle is known if it names a persona section or appears in one'sKnown asfield. Match generously. - In neither, report it in the proposal, one line per handle, and name the near miss when a known handle plausibly means the same person:
New owner handles:
- @priya.nair -- not in open.md and not in personas.md. open.md already uses
@priya. Same person?
"Same person?" invites a correction; the run never waits on it, so it never
fails the same-turn conditions and never goes in "Questions before I write".
On the same-turn path it is shown beside the written lines. It runs before
the write either way. Never rewrite a handle, never merge entries because they
look like one person, and never write personas.md -- offering
/daikenja:remember-persona is fine. With no personas file configured, say the
comparison was open.md alone.
Check for duplicates first
For each candidate, look for an entry that already records the same fact.
Same subject is not the same fact. A standing rule and one project's call stay separate entries even when they read alike. The test is what would have to change for the entry to stop being true: if the answers differ, they are two facts.
- The same fact, already there. Propose an edit to that entry, quoting it. Do not append a near copy.
- A decision that replaces one in force. Propose editing the old entry in
place, or deleting it and adding the new one.
DECISIONS.mdis current-only: nothing is marked superseded. - A decision that conflicts with one in force without clearly replacing it. Ask which one holds. The answer is written; the conflict never is.
- An open item the material settles. Propose deleting its line, and the
DECISIONS.mdentry when it was settled by a decision, in the same batch. When another item'sBlocked by:names it, offer to drop that prefix too. - Genuinely new. Propose a new entry.
Two more branches open here, each in project-log-reference.md, and both set
the date on the open items this run writes:
- Most items are older than the run -- recording a project that has history. Read § Backfilling an existing project.
- The run is
project-log via meeting-review. Read § A meeting date handed over bymeeting-review.
Show the proposal
Show exactly what will be written, verbatim, grouped by file, in one fenced block, each file under its absolute path -- a run by key may write far from the current directory. Every line the user approves lands in the file byte for byte.
C:/GitHub/atlas/DECISIONS.md
## Delivery (new area)
Paths: `pipelines/`
+ - **The reload runs as a pipeline, never as a manual script.** — a manual
run skipped the row-count check twice. Revisit: never. Source:
https://example.com/atlas/thread/88
C:/GitHub/atlas/.daikenja/open.md (creating it from the template)
Open items
+ - 2026-08-14 -- @carlos -- Confirm the reload window with the data team.
- - 2026-08-09 -- @carlos -- Decide whether the reload is scripted or a pipeline.
Not kept:
- <decision> -- <which keep test it fails>
New owner handles:
- <handle> -- not in open.md and not in personas.md. <near miss, if any>
Questions before I write:
- <anything you could not settle, one line each>
+ marks a line added, - a line deleted, and an edit shows both. Drop any
block that is empty rather than writing a heading with nothing under it. Get
today's date from the environment -- date +%Y-%m-%d, the local date --
never from memory.
Keep the proposal to what the material supports. Five clean entries beat twelve padded ones.
Step 6: wait
Stop and wait for the user.
- Approved. Write it.
- Partly approved ("just the first two"). Write only what was approved. Do not argue for the rest.
- Edited ("change the owner to @sam"). Show the corrected block and wait again. It re-opens no settled question.
- Rejected. Write nothing. Say nothing was written.
Silence is not approval. Neither is the user replying about something else.
Step 7: write
- A new open item, context link or source goes directly under its heading.
- Closing an item deletes its line and its continuation lines.
- A new decision goes at the end of its area, or a new area at the end of the file, unless the user placed it.
- An edit changes the line in place. Nothing moves.
- A missing version line is added as the file's first line, as the proposal showed.
Touch nothing else. Do not reorder, reformat or tidy either file, and do not normalize a line a human wrote by hand.
Step 8: confirm
Confirm in one or two lines: what was written, to which files, topic first. Then say the change is not committed:
Wrote 2 entries -- the reload decision to C:/GitHub/atlas/DECISIONS.md, and
the reload-window item to C:/GitHub/atlas/.daikenja/open.md. Not committed: commit them with
the work they belong to.
When a written entry names another document in the project, offer the follow-up: "The reload decision points at docs/reload.md -- update it to match?" Updating it is outside this skill's write scope, so it happens only on the user's yes, as its own change.
Failure cases
project-log-reference.md § Failure cases. Read it the moment a run meets a
situation the steps above do not settle, and before improvising a way through
one.
What this skill does not do
project-log-reference.md § What this skill does not do. Read it when a run is
about to do something no step above told it to.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |