retrospect-session

Retrospect Session

Overview

Consolidate session experience into long-term executable rules, uniformly maintained in docs/rules/, and ensure that project-level prompts always reference the latest rules.

Goals

1. Distill "transferable, executable" lessons from the current session.
2. Merge and reflect on the existing content of docs/rules/ , rather than only appending new entries.
3. Update (or create) the project-level prompts AGENTS.md and CLAUDE.md, establish references to docs/rules/*.md and explain the scope of the rules.
4. Standardize the rule document format according to best practices, control its scale, and ensure executability and maintainability.

Mandatory Outcomes

1. When this skill completes, you must simultaneously check and synchronize:
   • docs/rules/*.md
   • AGENTS.md
   • CLAUDE.md
2. If AGENTS.md or CLAUDE.md does not exist, you must create a minimal usable version (see the template below).
3. If you find that a newly added rule file is not referenced by the project-level prompts, you must add the reference and a one-sentence summary.
4. It is not allowed to only update docs/rules/ while skipping synchronization of the project-level prompts.

Operating Modes

Incremental Update

• Use only when this change involves 1-2 items docs/rules/*.md files, and no cross-file duplication, responsibility conflicts, or obvious topic drift is found.
• Use only when the existing topic boundaries are still clear, and AGENTS.md / CLAUDE.md only requires minor synchronization of references or summaries.
• Focus on local supplements, lightweight merges, and small-scope revisions, without introducing structural rearrangement.

System Restructure

• Focus on a complete inventory, finalizing the target structure, and rewriting governance actions, no longer relying on patch-style local appends.
• Applicable to scenarios that require rewriting, merging, splitting,Retire or Migrate rules.
• By default, first determine whether System Restructureis needed, rather than defaulting to Incremental Update。

Restructure Triggers

• Involves 3 or more rule files.
• Synonymous rules are duplicated across files.
• A single file carries multiple topics.
• The existing topic boundaries can no longer accommodate new lessons.
• The project-level index descriptions are inconsistent with actual responsibilities.
• Need to decide whether to keep, merge, migrate, or Retire old rules.

Workflow

1. Assess Current System

   • Review the goals, key decisions, failed attempts, rework points, and effective practices in the current session, and clarify the structural problems to be governed this time.
   • Read docs/rules/**/*.md、AGENTS.md、CLAUDE.md, first determine whether Restructure Triggersis satisfied; if so, enter System Restructure, otherwise follow Incremental Update。
   • Incremental Update focuses on local updates, lightweight merges, and small-scope revisions;System Restructure only then enters complete target structure design and reorganization actions.

2. Build Rule Inventory

   • Incremental Update Under this, only inventory the rule files directly related to this local update;System Restructure Under this, inventory the responsibility boundaries, coverage scope, and inter-file relationships of all relevant rule files.
   • Mark duplicate rules, conflicting statements, topic drift, overlapping responsibilities, and places where the project-level index is inconsistent with the actual structure.
   • Do not just record file names; instead form a structural view of "which rules govern what, and where things have become distorted".

3. Design Target Structure

   • System Restructure next, before rewriting, first decide which content should be kept, added, merged, split, migrated, or Retire。
   • Incremental Update next, make only the minimal structural decisions for entries that need adjustment within this local scope, without expanding into a global reorganization.
   • Clarify the final responsibility boundaries of each topic file, then determine the writing order and persistence method.
   • If the target structure requires adjusting the index scope of the project-level prompt, finalize the structure first, then proceed to the synchronization step.

4. Apply Rewrite / Merge / Split / Retire / Migrate

   • Execute rewriting, merging, splitting,Retire and Migrate, prioritizing structural issues rather than appending in a disorderly manner to the original file.
   • Rewrite: When file responsibilities are mixed or a local patch cannot restore the structure, rewrite the topic file as a whole.
   • Merge: When two files constrain the same type of decisions and differ only in historical wording, merge them into one more stable topic.
   • Split: When one file covers multiple independent scenarios at the same time and continued coexistence would reduce retrievability, split it into multiple files.
   • Retire: When an old rule is fully covered by a more stable and more executable rule, retire the old entry and no longer keep it alongside the others.
   • Migrate: When a rule is still valid but its assigned topic is no longer appropriate, migrate it to a more suitable file and record the reason.
   • When a topic file is expected to exceed 200 lines, split it in advance into shards such as topic-part-1.md、topic-part-2.md , and keep the directory index and applicability notes in the main file.

5. Sync Project Prompts

   • After the rule structure is finalized, then synchronize AGENTS.md / CLAUDE.md。
   • update the file paths, purpose summaries, and reading conventions of the ## Rules Index to ensure the index reflects the current real structure.
   • If the two project-level prompts differ in description, unify them into a version consistent with the current governance result.

6. Run Consistency Checks

   • Check whether there is still cross-file duplication, unclear responsibility boundaries, rule drift, or one-off experience mistakenly written as a long-term rule.
   • Check whether the AGENTS.md in CLAUDE.md and Rules Index is consistent with docs/rules/*.md .
   • Check whether the rule wording still supports executable and verifiable long-term maintenance.

7. Report Governance Changes

   • Report the result of this mode judgment: whether it is Incremental Update or System Restructure, and the basis for that judgment.
   • Report the governance actions actually executed, not just the files modified, for example what was merged, split, migrated,Retire and rewritten.
   • Explain how this governance eliminated duplication, conflicts, drift, or index distortion, and which stable rules were retained.

Abstraction Standard

• Do not write the specific events in this session verbatim as long-term rules.
• First identify repeatable failure patterns, then refine them into trigger conditions, actions, and verification methods.
• Session-local, non-transferable incidental experience does not enter the long-term rule base; only session experience that can be abstracted into reusable rules should be written into docs/rules。

Rule Writing Standard

• Prefer writing "principle + trigger conditions + execution actions + verification method".
• Keep the main file concise: retain only high-frequency, stable rules; place detailed rules in docs/rules/*.md and reference them in the project-level prompt.
• Avoid empty wording in rules: avoid unverifiable statements such as "pay attention to code quality".
• Keep the language concise and avoid tautology.
• If information is insufficient, first write the minimum viable rules and supplement them through later iterations.

Rules document templates (docs/rules/*.md)

# <主题名称>

## Scope
- 该文件适用的任务范围与边界。

## Rules
1. 当 <触发条件> 时，必须/应当 <动作>。
   - Rationale: <为什么这样做>
   - Verification: <如何判断已满足>
2. ...

## Anti-Patterns
- <常见错误> -> <正确做法>

## Change Log
- YYYY-MM-DD: <新增/合并/冲突取舍摘要>

Format requirements:

• Titles use # level-one headings; fixed level-two headings:Scope、Rules、Anti-Patterns、Change Log。
• Rules must be numbered; each rule must be verifiable.
• Vague statements are prohibited (such as "pay attention to quality" or "optimize as much as possible").
• File names must be kebab-case and consistent with the topic.

Project-level prompt template (minimum viable)

When AGENTS.md or CLAUDE.md is missing, create a file containing the following minimum structure:

# Project Agent Guide

## Rules Index
- [docs/rules/<file>.md](docs/rules/<file>.md): <该规则文件约束范围的一句话说明>

## Usage
- 执行任务前，先读取与任务最相关的规则文件。
- 若新增 `docs/rules/*.md`，必须同步更新本文件的 `Rules Index`。

Output template (when replying to the user)

## 规则沉淀结果

### 治理模式判断
1. 本次属于：增量更新 / 体系重整
2. 判断依据：<为何采用该模式，重点说明重复、冲突、漂移、索引失真或变更规模>

### 本次更新文件
1. docs/rules/xxx.md（新增/更新）
2. docs/rules/yyy.md（新增/更新）
3. AGENTS.md（新增/更新）
4. CLAUDE.md（新增/更新）

### 项目级提示词同步
1. 新增/更新引用：docs/rules/aaa.md -> <一句话摘要>
2. 新增/更新引用：docs/rules/bbb.md -> <一句话摘要>
3. 说明：<如有新增/调整 Rules Index 范围，写明同步原因与影响>

### 关键结构调整
1. 重写（Rewrite）：X -> X'（原因：<为何职责混杂、局部 patch 无法恢复结构或需要整体重整>）
2. 合并：A + B -> C（原因：<为何应合并为单一职责或单一决策面>）
3. 拆分：X -> X-part-1 / X-part-2（原因：<为何必须拆分，若触发 200 行分片策略，写明主文件与分片文件>）
4. 迁移：A -> B（原因：<为何主题归属更适合迁移后的文件>）
5. 废弃（Retire）：X -> Retire（原因：<为何旧规则已被更稳定的规则完全覆盖>）

### 治理结果
1. 消除：<本次消除了哪些重复、冲突、漂移或索引失真>
2. 保留：<本次保留了哪些稳定规则或稳定结构>

### 新增/强化的规则摘要
1. ...
2. ...
3. ...

Boundaries and exceptions

• docs/rules/ does not exist: first create the directory, then continue writing.
• AGENTS.md or CLAUDE.md does not exist: create it according to "Project-level prompt template (minimum viable)".
• If the format of historical rules is chaotic: first normalize the structure, then classify and rewrite.
• If the topic is unclear: first place it in the closest topic, and note "pending later refactoring" in the change record.