X-Financial/.codex/skills/agent-change-log/SKILL.md

---
name: agent-change-log
description: Use when working in X-Financial after bug fixes that need a split dev log, when maintaining document/development/YYYY-MM-DD/dev-logs/bugs, or when generating the daily 17:00 combined work-logs.med from same-day feature docs and bug logs.
---

# Agent Change Log

## Overview

This skill keeps split development logs for X-Financial. Bug fixes are recorded under the same-day `dev-logs/bugs` folder. Daily summaries combine same-day feature documents and bug records into one `work-logs.med`.

The log should sound like a careful teammate writing for tomorrow's teammate: concrete, warm, and honest.

## When To Use

- After fixing a bug.
- When a post-commit hook detects a bug-like commit.
- At the daily 17:00 summary pass.
- Before updating the log in a branch where other agents may have pushed commits.
- After verification, so the entry can include what was actually checked.
- When a failed attempt changed files, generated artifacts, or revealed a risk worth preserving.

Do not create legacy `document/work-log/YYYY-MM-DD.md` entries for new work.

## Log Location

Use the same date root as development documents:

```text
document/development/YYYY-MM-DD/
├── feature/<feature-point>/CONCEPT.md + TODO.md
├── dev-logs/bugs/<bug-slug>.md
└── work-logs.med
```

If the date folder exists, reuse it. If not, create it.

## Bug Log Structure

For bug fixes, create or update one file per bug:

```text
document/development/YYYY-MM-DD/dev-logs/bugs/<bug-slug>.md
```

The file must contain `## 修复记录` and timestamped bullets similar to the old `当日工作内容`.
Do not add `遗留问题` or `TODO` sections to bug logs.

Use the helper when possible:

```bash
python3 tools/agent-change-log/update_change_log.py \
  --kind bug \
  --bug-title "<bug 名称>" \
  --bug-slug <bug-slug>
```

## Required Git Check

Before writing or updating a bug log, manually check Git for upstream and local-ahead commits from other agents.

Run:

```bash
date '+%Y-%m-%d %H:%M:%S %Z'
git fetch --all --prune
git status -sb
git rev-parse --abbrev-ref --symbolic-full-name @{u}
git log --oneline --decorate --max-count=20 HEAD..@{u}
git log --oneline --decorate --max-count=20 @{u}..HEAD
```

Rules:

- Treat `git fetch --all --prune` as the default safe "pull check"; it updates remote refs without merging into a dirty worktree.
- Treat `HEAD..@{u}` as upstream commits not yet in local history.
- Treat `@{u}..HEAD` as local commits not yet in upstream history; these may also come from another agent working in the same checkout.
- If the worktree is clean and the branch is only behind upstream, `git pull --ff-only` may be used to fast-forward before analysis.
- If the worktree is dirty, diverged, or likely to conflict, do not merge/rebase automatically. Record the upstream commits from `HEAD..@{u}` in the bug fix entry.
- If there is no upstream branch, record that fact in the bug fix entry and continue with local-only logging.
- When `HEAD..@{u}` has commits, summarize those commits in the bug fix entry before describing local edits. Mention commit hash, subject, and inferred impact.
- When `@{u}..HEAD` has commits that were not created in the current task, summarize them too, because another local agent may have committed without pushing yet.
- When no upstream or local-ahead commits exist, still record "Git 提交检查：未发现 upstream 新提交或本地 ahead 新提交" in the work entry.

## Bug Entry Rules

1. Get the current local time first:
   ```bash
   date '+%Y-%m-%d %H:%M:%S %Z'
   ```
2. Run the required Git check and capture whether upstream or local-ahead has new commits.
3. Ensure `document/development/YYYY-MM-DD/dev-logs/bugs/` exists.
4. Create or update one `<bug-slug>.md` file for the specific bug.
5. Append a new timestamped bullet under `## 修复记录`.
6. Mention Git commits, changed files or modules, the operation, the intent, and the verification result.
7. Do not add leftover issue or TODO sections.

## Daily Summary

At 17:00 every day, generate the combined work log:

```bash
python3 tools/agent-change-log/update_change_log.py --kind summary
```

This reads:

```text
document/development/YYYY-MM-DD/feature/
document/development/YYYY-MM-DD/dev-logs/bugs/
```

Then writes:

```text
document/development/YYYY-MM-DD/work-logs.med
```

The summary should cover:

- Today's feature points from `feature/*/CONCEPT.md` and `TODO.md`.
- Today's bug fixes from `dev-logs/bugs/*.md`.
- A concise combined analysis of what changed that day.

## Entry Rules

- For each bug entry, append a new timestamped bullet under `## 修复记录`.
- Mention Git commits, changed files or modules, the operation, the intent, and the verification result.
- Do not write `遗留问题`.
- Do not write `TODO`.
- If the change is a feature rather than a bug, use the development document skill to keep `feature/<feature-point>/CONCEPT.md` and `TODO.md` current instead of writing a bug log.

## Writing Style

- Write in Simplified Chinese.
- Be specific and a little human: "我把...", "这次先...", "还需要留意..." are good.
- Keep the tone factual. Do not turn the log into a victory lap.
- Prefer concise file names and module names in prose, but include enough context to find the change.
- Work content should be detailed enough that a future agent can continue without asking "你到底改了啥？"

## Bug Entry Template

```markdown
- HH:MM：记录 bug 修复：<bug 名称>。
  - Git 提交检查：<git fetch 后 HEAD..upstream 与 upstream..HEAD 的结果；没有就写未发现 upstream 或本地 ahead 新提交>。
  - 修改：<文件/模块>，<做了什么>。
  - 操作：<运行了什么命令、迁移了什么状态、重启了什么服务等>。
  - 验证：<测试/构建/检查结果；如果没跑，说明原因>。
  - 影响：<用户可见变化或工程边界变化>。
```

## Final Response Checklist

Before saying work is complete:

- For bug fixes, today's bug log exists under `document/development/YYYY-MM-DD/dev-logs/bugs/`.
- For non-bug feature work, relevant `feature/<feature-point>` documents are current.
- Git check ran for bug logs, and upstream plus local-ahead commits were summarized or explicitly marked as absent.
- No new legacy `document/work-log/YYYY-MM-DD.md` entry was created.
- The final response mentions whether a bug log, feature document, or daily `work-logs.med` was updated.