devlog

# DEVLOG Skill

Maintain **two** local-only project files that work together:

| File | Role | Style |
|---|---|---|
| `DEVLOG.md` | Chronological log of what was done, planned, and learned | Append-only, dated entries |
| `LESSON.md` | Aggregated knowledge base of problems → root causes → solutions | Indexed, category-organized, reusable |

Rule of thumb: **DEVLOG.md records the journey; LESSON.md records the wisdom.**

Both files are **local-only** — they must never reach the remote repository, and
the ignore rules for them must not be committed either. This is achieved with
`.git/info/exclude` (a per-repo, never-tracked file), **not** `.gitignore`.

## When to Use

Invoke this skill when any of the following happen:

- Starting a new coding task in a project
- Completing a coding task or a significant sub-step
- Making an architectural or design decision
- Fixing a non-trivial bug
- Discovering a library / framework gotcha
- User says things like "log this", "记一下", "记到 DEVLOG", "记到 LESSON",
  "做个总结", "加到 LESSON", "save a lesson", "remember this gotcha"

## When NOT to Use

- **Short-lived TODOs** — use the project issue tracker or a local TODO file.
- **Public-facing documentation** — use the project wiki or a shared doc.
- **Free-form chat summaries** — use conversation search, not a log file.
- **Secrets, credentials, or PII** — never store in either file, even though
  they are local.
- **One-line trivial commits** — skip; only log meaningful changes.

## First-Run Setup

On first invocation in a project (or if either file is missing):

1. Run the platform-appropriate setup script — it creates both files from
   templates and registers them in `.git/info/exclude`:

   ```bash
   # POSIX (bash, zsh, Git Bash, WSL)
   ./.trae/skills/devlog/scripts/setup.sh
   ```
   ```powershell
   # Windows PowerShell 5+
   ./.trae/skills/devlog/scripts/setup.ps1
   ```

   The script is **idempotent** — safe to re-run.

2. Verify with: `git check-ignore -v -- DEVLOG.md LESSON.md`
   - Expected: both lines reference `.git/info/exclude`.

3. Tell the user both files are intentionally local-only.

If the files already exist, just read them for context and append. Never
recreate. For background on the ignore choice, see
[references/git-exclude-explained.md](references/git-exclude-explained.md).

---

# DEVLOG.md

Append-only chronological log.

## Entry Format

```markdown
## [YYYY-MM-DD] Brief title

**What:** One sentence describing what was done.
**Why:** The trigger, problem, or motivation.
**How:** Key implementation details (non-obvious only).
**Learned:** Gotchas, patterns, follow-ups, or open questions.
```

Conventions:

- Date in user's local timezone, ISO `YYYY-MM-DD`.
- Title: short noun phrase, no period.
- Bullets are fine inside any field.
- Never edit or delete old entries — only append.
- When a fix surfaces reusable knowledge, add a pointer:
  `**Lesson:** see LESSON.md → <Category> → <slug>`

## Workflow

### On task start

1. Read `DEVLOG.md` (if present) for context and the `## Planned` section.
2. If a `## Planned` item matches the current task, note it in the upcoming entry.

### On task completion / decision

1. Read the current `DEVLOG.md`.
2. Append a new `## [YYYY-MM-DD]` block under the existing content.
3. If a planned item is now done, move it from `## Planned` into a dated entry
   with a `[Done]` prefix in the title (do not delete the original line — strike
   it through or annotate it).
4. Add follow-up items to `## Planned` if any.
5. **Promote** to `LESSON.md` if the learning is reusable (see below).

### Hygiene

- If the file grows past ~300 entries, split by year (`DEVLOG-2026.md`) and keep
  `DEVLOG.md` as an index.
- Never include secrets — treat it as plain text even though it's local.

---

# LESSON.md

Aggregated, searchable knowledge base of problems and their solutions. Where
`DEVLOG.md` is a stream, `LESSON.md` is an index — each lesson is a stable
entry that can be referenced, linked, and re-applied.

## When to Promote DEVLOG → LESSON

Promote a `DEVLOG.md` entry into `LESSON.md` when **any** of these is true:

- The same root cause could appear again in this project (or in similar ones).
- The fix took more than ~15 minutes of investigation.
- A library / framework behaved counter to docs or intuition.
- The user asked "why did we do it this way?" — i.e. the rationale is valuable
  out of context.

If the issue was trivial or one-off, keep it only in `DEVLOG.md`.

## Entry Format

Group by **category** (one `##` heading per category). Slugs are stable IDs you
can link to.

```markdown
## <Category, e.g. "Library / React">

### <YYYY-MM-DD> short-slug

- **Problem:** One-sentence description of the symptom.
- **Root cause:** Why it happened.
- **Solution:** The fix (commands, code, config).
- **How to avoid:** Checklist, lint rule, or convention to prevent recurrence.
- **Related:**
  - `DEVLOG.md` → `## [YYYY-MM-DD] <title>`
  - upstream issue / docs link
```

For the canonical category list and naming rules, see
[references/categories.md](references/categories.md).

Conventions:

- `Problem` is the user-visible symptom. `Root cause` is the underlying reason.
  Keep them separate — symptoms recur even when causes change.
- Slug = lowercase-kebab, ≤ 5 words, action-oriented
  (e.g. `push-fails-on-spaces-in-path`).
- Newest lesson at the **top** of its category, so the freshest knowledge is
  most visible.

## Workflow

### When a non-trivial bug is fixed

1. Open `LESSON.md` and pick (or create) the right category.
2. Add a new entry at the top of that category with the template above.
3. Cross-link from the matching `DEVLOG.md` entry
   (`**Lesson:** see LESSON.md → <Category> → <slug>`).
4. If this exact lesson already exists, **append** a new dated occurrence under
   it instead of creating a duplicate — frequency matters.

### When starting a task

1. Read the relevant categories in `LESSON.md` before designing the approach.
2. If the user says "hav