# Milestone > Use BEFORE running /compact or when a significant task milestone is reached to document technical decisions, experiments, and progress. Use when this capability is needed. - Skill: `tomevault-io/milestone-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/milestone-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/milestone-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/milestone-2 --- # Milestone Reporting Skill ## Overview This skill defines the protocol for documenting project milestones. It ensures that technical decisions, experimental results, and architectural changes are preserved beyond the short-term memory of a single session. ## When to Use - **BEFORE /compact**: You MUST run this skill manually before compacting context. - **Milestone Reached**: Use when you have finished a meaningful piece of work (feature, fix, refactor). ## Workflow ### Phase 1: Context Saturation (Mandatory) Before generating any files, you MUST perform a deep audit of the work done. 1. **Identify Scope**: * Review `git log` to identify all commits since the last milestone. * If no commits exist, include staged changes (`git diff --staged`). 2. **Recursive Audit (Anti-Hallucination)**: * **Trace**: For every modified file, identify its upstream callers and downstream dependencies. * **Read**: Use `Read` to verify the *source definitions* of changed functions. * **Verify**: Confirm you understand the *exact* technical logic, not just the intent. * **Constraint**: Do NOT proceed until you can explain the "Ripple Effects" and "Systemic Impact" for every change. ### Phase 2: Documentation Generation 1. **Generate Draft**: Use `python "~/.claude/skills/milestone/generate_draft.py"` to create a draft file and update the timeline. 2. **Fill Content**: Immediately read the generated draft and populate it using the `Write` tool. * **Data Source**: Use the knowledge gathered in Phase 1. * **Language Mandate**: All content MUST be in **Simplified Chinese (简体中文)**. 3. **Validation**: Verify the file is saved and the content matches the schema. ### Phase 3: Finalization (Summary Sync) After the report is written and verified, you MUST synchronize the summary back to the timeline index. 1. **Sync**: Run `python "~/.claude/skills/milestone/sync_timeline.py"`. 2. **Verify**: Check that `.claude/history/timeline.md` now contains the meaningful Chinese summary from your report. ## Content Standards (Strict) You MUST adhere to the following 4 rules when writing the report: 1. **Completeness (No Token Saving)**: DO NOT summarize, compress, or omit technical details to save space/tokens. You MUST preserve the FULL technical context, reasoning, and trade-offs. 2. **Negative Knowledge (Falsification)**: You MUST document *refuted* hypotheses and *failed* attempts. Explaining "why approach X failed" is as critical as "how approach Y succeeded". 3. **Style (Objective)**: Use formal, simple indicative sentences (`Subject` + `Verb` + `Object`). STRICTLY PROHIBIT unnecessary `Adjectives`, `Adverbs`, and `Metaphors` (e.g., "elegant solution", "quick fix"). 4. **Epistemic Humility**: DO NOT declare "Fixed" or "Solved" without empirical data (logs/tests). Use "Implemented" or "Attempted" for unverified changes. Do not predict future success. ## Core Pattern: The Milestone Report A milestone consists of two parts: 1. **Index (Timeline)**: A high-level reverse-chronological list in `.claude/history/timeline.md`. 2. **Report**: A detailed markdown file in `.claude/history/reports/YYYYMMDD_HHMMSS.md`. ## Report Schema (Strict Compliance) You must follow the schema defined in `~/.claude/skills/milestone/report_schema.json`. The generator script handles the skeleton; your job is to populate the content in **Chinese**. ## Discovery The history is indexed in `.claude/history/timeline.md`. Claude will refer to this index in `CLAUDE.md` to progressively discover past reports when needed. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/till-crazy-tears-us-apart) — claim your Tome and manage your conversions.