Skip to content

by-carlos/daikenja / skills/project-log

project-log

Verified

Records 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.

FileKindSize
SKILL.mdskill md19.5 KB
---
name: project-log
description: Records 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.
metadata:
  owner: Carlos
  version: 1
  writes: DECISIONS.md at a registered repository's root, and .daikenja/open.md in the project's home repository
---

# 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` -- the `DECISIONS.md` format:
  what gets kept, areas and `Paths:`, the entry shape, current-only.
- `${CLAUDE_PLUGIN_ROOT}/docs/open-format.md` -- the `open.md` grammar, the
  `Blocked 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 a `drive:` pointer. Step 5's
  owner check is the only thing here that reads `personas.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:

1. 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.
2. **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.
3. Resolve the files per `config-resolution.md` § Finding `DECISIONS.md` and
   `open.md`: `DECISIONS.md` at the root of every path in the entry, and
   `.daikenja/open.md` in the home repository, which is the **first** path.
   No match: the current directory is the one root.
4. Apply `config-resolution.md` § Legacy keys and unmigrated ledgers. A
   leftover `ledger:` key gets its one line and the run continues. A
   `paths: []` entry is "needs migration": its line, and stop. **An old ledger
   at `<home>/.daikenja/ledger.md` with no `open.md` beside it** is refused --
   whether or not a `DECISIONS.md` exists. Write that line, write nothing, and
   scaffold nothing:

   ```
   The ledger at <home>/.daikenja/ledger.md needs migration -- run /daikenja:setup-user.
   ```

5. 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.

1. **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.
2. **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.
3. **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.
4. **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. Read
  `project-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.name` from the config.
- Nobody identifiable means `@unassigned`. Write it out; never leave the field
  empty. An unowned item is what `project-gaps` reports.

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.

1. **Look in `open.md` first.** A handle that already owns an item there is
   known. Say nothing. This is the common case, and why `personas.md` is
   usually never read.
2. **Otherwise resolve `profile.personas`**, per `config-resolution.md`
   § Resolving `writing_style` and `personas`. The handle is known if it names
   a persona section or appears in one's `Known as` field. Match generously.
3. **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.md` is 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.md` entry when it was settled by a decision, in the same batch.
  When another item's `Blocked 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 by `meeting-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.
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall