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

---
name: agent-change-log
description: Use when working in X-Financial after bug fixes, new features, refactors, behavior changes, documentation edits, config edits, concurrent-agent Git commits, or any codebase modification that should leave an incremental human-readable work log.
---

# Agent Change Log

## Overview

This skill keeps a living, incremental work log for X-Financial. After each meaningful modification batch, write down what changed locally, what other agents already committed upstream, what was operated on, what remains uncertain, and what should happen next.

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

## When To Use

- After fixing a bug, adding a feature, refactoring, changing behavior, editing documentation, or changing config.
- Before the final response for any turn that changed files.
- 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 use for read-only investigation with no file changes unless the user explicitly asks for a record.

## Log Location

Use one file per day:

```text
document/work-log/YYYY-MM-DD.md
```

If the file does not exist, create it. If it exists, incrementally update it. Never replace the whole file just to add a new entry.

## Required Structure

Each daily file must use these sections in this order:

```markdown
# YYYY-MM-DD 工作日志

## 当日工作内容

## 遗留问题

## TODO
```

Keep this order stable. Add entries under the existing headings instead of creating duplicate headings.

## Required Git Check

Before writing or updating the daily 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}` and the blocker in `遗留问题`.
- If there is no upstream branch, record that fact in `遗留问题` and continue with local-only logging.
- When `HEAD..@{u}` has commits, summarize those commits under `当日工作内容` 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.

## 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. Append a new timestamped bullet under `## 当日工作内容`.
4. Mention Git commits, changed files or modules, the operation, the intent, and the verification result.
5. Add or update `## 遗留问题` whenever there is risk, uncertainty, skipped verification, design debt, Git divergence, or a likely follow-up.
6. Add or update `## TODO` with checkbox items.
7. When a TODO is completed, keep it in place and mark it as:
   ```markdown
   - [x] ~~任务内容~~（完成于 HH:MM，证据：...）
   ```

## 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 "你到底改了啥？"
- Leftover issues should include a suggested next step, not only a complaint.

## Work Content Template

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

## Leftover Issue Template

```markdown
- HH:MM：<遗留问题或风险>。建议下一步 <具体建议>。
```

## TODO Template

```markdown
- [ ] <下一步动作>（来源：HH:MM <上下文>）
- [x] ~~<已完成动作>~~（完成于 HH:MM，证据：<命令/文件/结果>）
```

## Final Response Checklist

Before saying work is complete:

- Today's `document/work-log/YYYY-MM-DD.md` exists.
- The Git check ran, and upstream plus local-ahead commits from other agents were summarized or explicitly marked as absent.
- `当日工作内容` includes this modification batch.
- `遗留问题` is either updated with real risks or explicitly says no new leftover issue for this batch.
- `TODO` contains new follow-ups and completed items are checked with evidence.
- The final response mentions that the work log was updated.