project-chronicles

What this skill does

# Project Chronicles

A two-track documentation system that preserves both implementation history and product/process
thinking across sessions. Built for the reality that future-you (or a future AI session) needs
to orient fast — and that these two kinds of knowledge decay differently.

## The core distinction

**Working log** — what changed and why. Tied to specific files, decisions, commits. Becomes
outdated when the code changes; that's fine, it's a record.

**Usage notes** — what you're learning about the problem, the product, the process. Observations
about how the system behaves, where friction surfaces, what the work wants to be. Stays true
(or worth thinking about) regardless of what's in the code.

**The litmus test:** "Would this note become wrong when the code changes?"
- Yes → working log
- No → usage note

A single session often produces both. Write to each when the session warrants it.

---

## Phase 1: Detect existing structure

Before proposing anything, look at what's already there. Scan the project root for:

- Config files: `CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, or similar agent/session config
- Existing docs directories: `docs/`, `notes/`, `journal/`, `log/`, `.notes/`, or any folder
  that looks like it's collecting session or project context
- Any files that resemble working logs or usage notes (common names: `CHANGELOG.md`,
  `working-log.md`, `notes.md`, `decisions.md`, `ADR/`)
- **Implementation-record systems** — a separate framework already responsible for recording
  per-change decisions. Candidates: `openspec/changes/` (OpenSpec), `docs/adr/` or `decisions/`
  (Architecture Decision Records), a `specs/` + `changes/` pair, an actively-maintained
  `CHANGELOG.md` with decision-style entries, or a strong issue/PR discipline where decisions
  live in GitHub/Linear. The signal is that the project already has a place where "what
  changed and why" gets written down on every change.

Present what you found. Be specific: name the files and folders, describe what they appear to
contain, and explain how you'd integrate rather than replace.

If an existing docs structure is close to this pattern (even with different names), say so and
ask whether to adapt it or set up alongside it.

If an implementation-record system was detected, flag it explicitly — its presence changes the
Phase 2 proposal (see "Delegated working-log mode" below).

---

## Phase 2: Confirm configuration

Propose defaults based on what you found, then confirm with the user. The questions that matter:

1. **Docs root** — where should the working log and usage notes live?
   Default: `docs/`. If something like `notes/` already exists and makes more sense, propose that.

2. **Delegated working-log mode** — only ask this if an implementation-record system was
   detected in Phase 1. Propose: "this project already records per-change decisions in
   `<detected path>`. Want to skip the working-log track here and only scaffold usage notes?
   The session-start config will point at `<detected path>` for the historical record."
   This avoids double-bookkeeping — agents won't keep writing working-log entries alongside
   the other system's per-change artifacts. If yes, skip questions 3 below; the working-log
   structure question becomes irrelevant.

3. **Working log structure** — single file or subfolder? *(skip in delegated mode)*
   The right choice depends on how much the project will accumulate over time.
   - **Single file** (`{docs-root}/working-log.md`) — good default for most projects. Simple,
     low friction, easy to scan. Fine until it gets long enough to be unwieldy.
   - **Subfolder** (`{docs-root}/working-logs/YYYY-QN.md`) — worth it when you expect many
     sessions over months or years and want to avoid one enormous file. One file per quarter
     is a natural cadence. Could also be monthly or per-major-version.
   Ask the user which fits their project's expected lifespan and pace. Default to single file
   unless they know this will be a long-running project.
   If there's an existing changelog or decisions log, ask if it should be converted or kept separate.

4. **Usage notes location** — subfolder name.
   Default: `{docs-root}/usage/`.
   These are typically named by topic or session, not by date — propose freeform naming here.

5. **Session-start config** — which file gets the "read these first" instructions?
   Look at what exists: if there's a `CLAUDE.md` or `AGENTS.md`, propose injecting a section.
   If nothing exists, offer to create one. Ask which they prefer.

6. **Naming conventions** — are there project-specific naming patterns to follow?
   If the project already has a README with style conventions, or a CLAUDE.md with rules,
   inherit those rather than inventing new ones.

Present the proposed config clearly (a simple list is fine) and ask for confirmation or changes
before writing anything.

---

## Phase 3: Scaffold

Create only what doesn't exist. Never overwrite. In delegated mode, skip the working-log
directory and file — only usage notes and the session-start injection get scaffolded.

### Directories

Create whatever directories are needed based on the agreed structure. If using a subfolder for
working logs, create it. If using a single file, no extra directory needed — just the docs root.
Usage notes always get their own subfolder. Skip creation for anything that already exists.

### Initial working log file *(skip in delegated mode)*

Create the working log file if none exists. The structure is the same regardless of whether
you're using a single file or a subfolder — the difference is just the path:

- Single file: `docs/working-log.md`
- Subfolder: `docs/working-logs/2026-Q2.md` (or whatever period is current)

Use this structure:

```markdown
# Working log — [project name], [period]

Living source of truth for implementation decisions. Read when starting work; append when
finishing a significant block. Any agent or human collaborator should include their signature.

## Entry template

---

## YYYY-MM-DD — Sentence-case summary of what happened

**Agent**: [agent name + model, e.g. Claude Code / Sonnet 4.6, Cursor / GPT-4o, human]
**Scope**: [brief area, e.g. auth, schema, UI, infra]

What was done, decided, or changed. Keep it concise — link to files or commits where details
live. Note any open questions or follow-ups.

---
```

If a working log file already exists for the current period, leave it alone.

### Usage notes directory

Create the folder. No initial file needed — usage notes are written as they emerge, named
by topic. Include a brief `README.md` so the purpose is clear to anyone landing there:

```markdown
# Usage notes

Product and process observations: how sessions feel, where friction surfaces, what the work
wants to be. Distinct from the working log — these stay relevant regardless of code state.

Name files by topic, not date. Write when a session produces insight worth keeping.
```

### Session-start injection

If injecting into an existing config file (`CLAUDE.md`, `AGENTS.md`), add a clearly delimited
section. Don't touch surrounding content.

**Default mode** — when this skill owns the working-log track:

```markdown
## Session start

Before replying substantively to the first message in any session, orient from:

1. The most recent working log entry in `{working-logs-path}/` — what changed recently.
2. The last one or two files in `{usage-notes-path}/` — what we're learning about the work. Scan filenames first; read the most recent in full.

Make sure the logs are written comprehensibly for someone being onboarded to the project.

If a usage note flags unresolved questions or thinking that's ahead of implementation, carry that forward rather than re-deriving it.
```

**Delegated mode** — when another system (OpenSpec, ADRs, etc.) owns the implementation record.
Parameterize the first item to point at whatever was detected in Phase 1:

```markdown
## Session start

Before replying substantively to t