capture

name

capture

description

Adaptive-depth session recap and low-friction checkpoint capture for weekly reporting and decision replay. Use this skill for "/lode:capture" or when the user signals end of a work session — e.g. "收工", "今天到这", "done", "wrap up", "that's it for today", "好了", "先这样". Also trigger on explicit requests like "记录变更", "log changes", "记一下今天做了什么", "记一下当前进展", or "checkpoint". Do NOT trigger when the user is simply saying goodbye or switching topics.

Adaptive-Depth Session Recap

Session-end and checkpoint signal extraction. When the developer wraps up work or explicitly asks to checkpoint the current progress, read the conversation context and produce raw entries rich enough for weekly outlines, monthly reviews, decision roadmaps, and session-start recall.

The goal is not a chronological diary. Capture the durable engineering signal: why the work happened, what was decided, what was tried, what changed, and what future sessions need to remember.

Zero-Config Mode

This skill works with or without a configured knowledge vault:

• With vault: entries are written to {vault}/raw/weeks/{ISO-week}/{project-slug}.json; durable artifact indexes are written to {vault}/raw/artifacts/{project-slug}.json when applicable. Output is quiet by default: after a successful write, return only a short confirmation unless the user explicitly asks for verbose output.
• Without vault: entries are rendered as structured Markdown directly in the conversation. No files written, no directories created. A one-line setup hint follows the output.

Zero-config mode is best-effort. Fill every field that can be inferred from the conversation, but do not interrogate the user only to satisfy a schema field. Depth enforcement is warning-based in the helper, not a hard block.

Capture Modes

Default mode is a session-end recap. It is triggered by /lode:capture, "收工", "done", and similar wrap-up signals.

Checkpoint mode is a mid-session progress record. Trigger it when the user says "checkpoint", "记一下当前进展", /lode:capture checkpoint, or clearly asks to record the current state before continuing. A checkpoint is not a diary entry. Capture only durable stage signals:

• A decision made or clarified
• A meaningful phase completed or unblocked
• A risk, blocker, or open question discovered
• An abandoned approach and the reason it was dropped
• A next-session or next-phase entry point

Checkpoint entries use the same raw entry schema as session recaps. Prefer status: "ongoing" unless the checkpoint records a clearly completed phase, resolved repair, or chosen decision. Keep checkpoint entries shorter than session-end recaps, but still preserve the "why" when it is available.

Verbose output is opt-in. Treat "verbose", "show recap", "展开总结", or an explicit request to inspect the recap as a request to print the full Markdown recap after writing. Quiet output remains the default in vault mode for both session-end and checkpoint captures.

Auto-Capture (Optional)

When configured, /lode:capture can run automatically at session end via a Claude Code Stop hook. This eliminates the dependency on remembering to say "收工".

Enable: Set auto_capture.enabled: true in ~/.lode/config.yaml. /lode:cold-start-interview sets this by default for new configurations.

Hook configuration: Add to ~/.claude/settings.json under hooks.Stop:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/lode:capture"
          }
        ]
      }
    ]
  }
}

Disable: Set auto_capture.enabled: false in ~/.lode/config.yaml. Remove the hook entry from ~/.claude/settings.json to fully deactivate.

The hook runs best-effort — if the vault is not configured or the helper is unavailable, the skill falls back to Markdown output in the conversation.

Step 1: Classify The Session Archetype

Read the full conversation context and choose one primary archetype. Apply these rules in priority order:

1. If the session chose between approaches or design trade-offs → decision
2. If the session fixed a bug, regression, or reliability issue → repair
3. If the session explored a problem without shipping a fix or feature → investigation
4. If the session shipped a working feature or capability → build
5. Otherwise → maintenance

If multiple archetypes apply, choose the one with the strongest signal. A fix after exploration is usually repair; a feature that mainly records a design choice is usually decision. If uncertain, use build and fill the optional fields supported by evidence.

Step 2: Extract Report-Worthy Signals

Start with the decision landscape, then use files, commits, and commands as evidence. Extract in this order:

• Motivation: the problem, goal, or constraint that made the work necessary
• Exploration paths: approaches tried, outcomes observed, and trade-offs
• Abandoned alternatives: options rejected and why
• What changed: shipped capability, fix, refactor, decision, or risk
• Impact: what the work enables, prevents, simplifies, or changes downstream
• Open questions: unresolved decisions, risks, or next-session entry points
• Artifact context: durable artifacts created or materially changed

Prioritize signals that can appear in a weekly report:

• Shipped or meaningfully advanced capabilities
• Technical decisions, trade-offs, and rejected alternatives
• Risks, blockers, regressions, and follow-up work
• Prompt, schema, orchestration, migration, or contract changes
• Reliability, performance, validation, or developer-workflow improvements

Skip process-only noise unless it explains a larger report-worthy signal: formatting, import cleanup, file moves, generated files, local setup, or intermediate experiments that were fully replaced.

Group related work into logical units. A session that touched many files for one feature should usually produce one entry. Maximum 5 entries; 1-3 is the normal range.

Step 3: Generate Raw Entries

Follow references/weekly-ppt-convention.md. The change entry JSON shape is:

{
  "timestamp": "ISO 8601 (set by helper; LLM-provided value is overwritten with server clock)",
  "archetype": "decision | build | investigation | repair | maintenance",
  "type": "feature | fix | refactor | decision | risk",
  "summary": "1 sentence, engineering-level abstraction",
  "context": "1-2 sentences explaining why and impact",
  "source": "session-recap",
  "status": "done | ongoing | risk | decision",
  "related_docs": ["/absolute/path/to/doc"],
  "impact": "report-ready user, system, reliability, or workflow impact",
  "evidence_refs": ["commit SHA, issue ID, eval ID, or doc path"],
  "decision_threads": ["stable-decision-thread"],
  "lifecycle_transition": {
    "subject": "decision:stable-decision-thread",
    "from": "proposed",
    "to": "chosen",
    "reason": "Why this session changed the lifecycle state"
  },
  "source_refs": [
    {
      "type": "commit | issue | eval | doc | conversation | other",
      "ref": "stable source id",
      "path": "/absolute/path/when-local",
      "url": "https://example.com/when-remote",
      "note": "short evidence note"
    }
  ],
  "motivation": "why this work was needed now",
  "exploration_paths": ["approach tried -> observed outcome"],
  "abandoned_alternatives": ["approach rejected -> reason"],
  "open_questions": ["unresolved question or next-session entry point"],
  "root_cause": "repair-only: 1-2 sentence cause of the bug or reliability issue",
  "artifact_context": [
    {
      "artifact_path": "/absolute/path/to/artifact",
      "scope": "What this artifact governs",
      "delta": "What changed in this session",
      "open_questions": ["unresolved artifact question"],
      "source_of_truth": ["path/to/implementation", "path/to/tests"]
    }
  ],
  "sync_suggestions": ["Review DESIGN.md because the session changed a contract."]
}

Archetype Field Expectations

Archetype	Required when known	Purpose
decision	motivation, exploration_paths	Preserve why one approach won
build	motivation, impact	Explain what shipped and why it matters
investigation	exploration_paths, open_questions	Preserve findings without pretending work shipped
repair	motivation, root_cause	Keep the concrete failure path reusable
maintenance	core fields only	Avoid over-documenting low-risk cleanup

These are adaptive-depth expectations. In vault mode the helper logs warnings for missing archetype fields; it does not reject the entry.

Decision Tracking Fields

Add decision_threads when the entry belongs to a durable decision topic. Use stable slug-like terms; decision replay treats these as stronger than artifact hints or keyword-derived topics when assigning thread_id.

Add lifecycle_transition only when the session explicitly changes the state of an open question, risk, decision, or artifact. Use subject, from, to, and reason when known; leave the field absent instead of guessing.

Add source_refs when evidence needs typed structure. Each object must include type and ref; optional fields are path, url, note, and timestamp.

Fruit Check

Before accepting an entry, make sure its report-level claim has a real "fruit": a changed user, product, system, reliability, migration, or workflow state. Activity counts, commits, files touched, tokens, logs, and documents are evidence or inputs; they are not outcomes by themselves.

• work_stream groups related work for later reporting. It does not prove that the grouped work produced an outcome.
• summary states the factual change or decision at the boundary actually reached. Do not promote an experiment, partial implementation, or plan into shipped work.
• impact states an observed downstream effect when one is known. If it is prospective, label it explicitly with wording such as "expected to", "can", or "intended to"; never rewrite the expectation as an achieved result.
• status bounds every claim: done means the described scope completed, ongoing means progress only, risk is unresolved exposure, and decision records a choice rather than implementation.
• evidence_refs, source_refs, and artifact_context.source_of_truth support verification. Their existence does not by itself prove the impact claim.

If no fruit can be stated honestly, preserve a narrower decision, investigation, maintenance, or risk signal instead of manufacturing an outcome.

Artifact Context

Add artifact_context only when the session created or materially changed a durable artifact, such as DESIGN.md, PLAN.md, AGENTS.md, README, architecture docs, prompt contracts, schema contracts, migration notes, or checklists.

Each artifact context must include:

• artifact_path: absolute path to the artifact
• scope: what the artifact governs
• delta: what changed in this session
• source_of_truth: implementation, tests, prompts, schemas, or docs that make the artifact checkable
• open_questions: unresolved artifact-level questions, when present

When artifact_context is present and a vault is configured, also upsert an artifact index entry with scripts/lode_raw.py upsert-artifact. Use source: "capture". If artifact_index.enabled is false, config cannot be resolved, or the helper fails, skip the artifact-index side effect and continue.

Sync Suggestions

Add sync_suggestions when the entry mentions decisions, contract changes, prompt/schema changes, orchestration rules, or intent artifacts that may need human review.

Keep suggestions conservative. A suggestion means "this file may need review", not "this file is stale" and not "apply this diff".

Step 4: Output Or Write

Output Policy

Use quiet output by default whenever a vault write succeeds. This applies to manual /lode:capture, checkpoint capture, and auto-capture. Return only a short confirmation such as:

已记录 {N} 条进展 -> {slug} ({week})

If the user requested verbose output, also include the Markdown recap after the write confirmation.

Zero-config mode is always verbose because the conversation output is the only deliverable. Helper failures must not be silent: report the specific failure briefly, then provide the Markdown fallback recap.

Helper Resilience

The lode_raw.py helper is the canonical write path, but capture must not fail when the helper is unreachable:

1. Helper timeout: If python lode_raw.py resolve-config takes > 10 seconds, briefly report the timeout and fall back to Markdown output.
2. Helper missing: If the script file is not found (e.g., incomplete installation), briefly report the missing helper and fall back to Markdown output.
3. Parse errors: If the helper returns non-JSON, fall back to Markdown output and report the error to the user.
4. Write errors: If append-entry fails with a disk/permission error, fall back to Markdown output and report the specific error.

In all fallback cases, the Markdown output is the primary deliverable. The vault write is a side effect that must not block the recap.

Resolve {vault} using the standard priority order:

Priority	Location	Scope
1	.lode/config.yaml	Project-level override
2	~/.lode/config.yaml	Global default
3	$WEEKLY_PPT_PATH	Legacy fallback
4	~/.weekly-ppt/	Legacy fallback default

Use the bundled helper when available. Each helper call requires the JSON to be on disk as a file — the scripts read --entry / --artifact paths, not stdin.

Step 4a: Resolve config and write entry JSON to a temp file

python <this-skill>/scripts/lode_raw.py resolve-config --cwd "$PWD"

Then use the Write tool (not bash heredoc, pipe, or redirect) to write the entry JSON array to {project}/.lode/tmp-entry.json. The Write tool guarantees the file content is flushed to disk before the helper reads it. Do NOT use heredoc or cat > file — those can leave stale content from a previous session.

Step 4b: Append the entry

python <this-skill>/scripts/lode_raw.py append-entry \
  --entry .lode/tmp-entry.json \
  --cwd "$PWD"

The helper resolves config, calculates the ISO week, resolves the project slug, validates required fields, logs adaptive-depth warnings, and appends the entry object or array.

Step 4c: Clean up

rm .lode/tmp-entry.json

Delete the temp file only after Step 4b succeeds. If the helper fails, keep the temp file for debugging and fall back to Markdown output.

Artifact index entries

For each durable artifact index entry, follow the same Write → call → cleanup pattern:

1. Use the Write tool to write the artifact JSON to {project}/.lode/tmp-artifact.json.
2. Call the helper:

   python <this-skill>/scripts/lode_raw.py upsert-artifact \
     --artifact .lode/tmp-artifact.json \
     --cwd "$PWD"
   

3. On success, delete rm .lode/tmp-artifact.json.

If any helper call fails, fall back to Markdown output instead of blocking the recap.

Auto-registration

After successfully appending entries, ensure the project is registered in the knowledge vault:

python <this-skill>/scripts/lode_raw.py register-project --cwd "$PWD"

This is a best-effort side effect that keeps {vault}/raw/projects.json current for weekly and daily multi-project discovery. If the helper is unavailable or the call fails, do not block the recap.

Markdown Output Template

Use this template in zero-config mode or helper-failure fallback:

## Session Recap — {project-dir-name} ({date})

### {type}: {summary}

{context}

**Archetype**: {archetype}

{if motivation present:
**动机**: {motivation}
}

{if impact present:
**影响**: {impact}
}

{if root_cause present:
**根因**: {root_cause}
}

{if exploration_paths present:
**探索路径**:
- {path}
}

{if abandoned_alternatives present:
**放弃的方案**:
- {alternative}
}

{if artifact_context present:
**Artifact context**:
- {artifact_path}: {delta}
}

{if open_questions present:
**开放问题**:
- {question}
}

{if sync_suggestions present:
**需要同步检查**:
- {suggestion}
}

After the final entry, append:

配置 knowledge_vault 可以持久保存这些记录，并在周报、月报中自动复用。
运行 `/lode:cold-start-interview` 可在约 2 分钟内完成设置。

Confirmation

Vault mode:

已记录 {N} 条进展 -> {slug} ({week})

Use the fuller confirmation only when the user requested verbose output or when debugging a write issue:

记录了 {N} 条变更 -> {slug} ({week})
  写入: {vault}/raw/weeks/{week}/{slug}.json
  - [{archetype}/{type}] {summary}

Zero-config mode needs no extra confirmation because the Markdown recap is the deliverable.

Capture Receipt

After the vault-mode confirmation, append a 2-3 line receipt that gives the user immediate signal from what was just captured. Zero-config mode does not need a receipt because the full Markdown output already serves this purpose.

Receipt template:

📋 {最关键的 summary}
   ⚠️ {N} 个风险 · ❓ {N} 个开放问题 · 🔄 {N} 个放弃方案

Selection rules for the top summary:

1. If any entry has archetype: decision, use its summary.
2. Otherwise, if any entry has an impact field, use that entry's summary.
3. Otherwise, use the first entry's summary.
4. If there is only one entry, use its summary directly.

Signal counts — count across all entries written in this capture:

• Risks: count of entries with status: "risk" plus entries whose open_questions contain risk-related phrasing.
• Open questions: total count of all open_questions items across entries.
• Abandoned alternatives: total count of all abandoned_alternatives items across entries.

Omission rules:

• When a count is 0, omit that segment entirely rather than showing "0 个".
• When all entries are archetype: "maintenance", omit the 📋 prefix and use plain wording (e.g., the summary text without the emoji).

Checkpoint receipt is shorter — show only the top summary and open questions (if any). Skip the full signal-count line.

Example receipts:

已记录 3 条进展 -> lode (2026-W23)
📋 选择了 SQLite 而非 LevelDB 做本地缓存
   ⚠️ 1 个风险 · ❓ 2 个开放问题 · 🔄 1 个放弃方案

已记录 1 条进展 -> my-app (2026-W23)
📋 完成了用户认证模块的 API 端点

已记录 2 条进展 -> tools (2026-W23)
更新了依赖版本并清理了无用导入

Quality Gate

Before finalizing each entry, check:

• Does it explain why, not just what?
• Is archetype accurate from the conversation evidence?
• Are archetype-specific fields filled when available?
• Would this help a weekly report or future decision roadmap?
• Is the summary a report-level outcome, not a file-level description?
• Does the Fruit Check distinguish actual state change from activity or an expected effect?
• Does status limit the claim correctly, especially for ongoing work, risks, and decisions?
• Do evidence references support the claim rather than merely exist beside it?
• Are durable artifacts represented through artifact_context, not vague prose?
• For checkpoint mode, is this a durable stage signal rather than a progress log?

Anti-Patterns

• Do not fabricate fields to satisfy the schema.
• Do not ask confirmation questions just to enrich optional fields.
• Do not preserve process noise that would never appear in a weekly review.
• Do not use checkpoint mode to record command-by-command progress.
• Do not split one coherent feature across many entries.
• Do not write new entries with source: "arch-doc"; that source is legacy-only.
• Do not generate formal Stage/Pipeline architecture documents from this skill.