agent-impl-notes-log

Agent Implementation Notes — Running Log

Purpose

The phase meeting log (meetings/{date}_{topic}.md) is summative — written after work completes. By that point, dozens of micro-decisions made mid-flight are already lost to the commit diff. An impl-notes log fills that gap: a concurrent record of decisions, deviations, tradeoffs, and unresolved questions, written as they happen.

The user explicitly asked for this:

在你進行工作的同時，維護一個名為 implementation-notes.md 的持續更新檔案，記錄任何我應該知道的，關於實作如何偏離或詮釋規格的事項。

When to invoke

Subagent MUST invoke this skill at the start of any dispatch matching ANY of:

• Touches more than 3 files in production code.
• Implements behavior whose spec has known ambiguity (e.g., // UNCONFIRMED markers, "Unconfirmed ?" prerequisites).
• Introduces a new dependency, target, or module.
• Refactors existing code beyond a one-line fix.
• Any task with a PROPOSAL_DRAFT step in the AI Collaboration Mode workflow.

Subagent MAY skip this skill for trivial one-line fixes, pure typo corrections, or documentation copy edits.

File layout

Path: meetings/{YYYY-MM-DD}_{topic}.impl-notes.md

Paired naming with the phase meeting log. If the phase log is meetings/2026-05-20_phase-11-foo.md, the impl-notes is meetings/2026-05-20_phase-11-foo.impl-notes.md.

If multiple subagents work on the same topic on the same day, append a numeric suffix: meetings/2026-05-20_topic.impl-notes.2.md.

File format

# Impl Notes — {topic} ({date})

Status: IN_PROGRESS
Owner: {subagent type, e.g. "Senior Developer"}
Dispatched by: Leader
Started: {ISO timestamp}

## 設計決定 (Design decisions)

_What you chose when the spec was ambiguous. Include the spec reference._

- **{decision name}** — Spec `docs/design.md §X.Y` says "...". Ambiguous on Z. Chose **A** because [reason]. Alternative was B (see §折衷).

## 偏離 (Deviations)

_Intentional deviations from the documented spec. Include the spec reference and the why._

- **{deviation name}** — Spec says X. Implemented as Y because [reason]. Downstream impact: [what changes for callers / tests / docs].

## 折衷 (Tradeoffs)

_Alternatives considered and the reasoning for the current pick._

- **{tradeoff topic}** — Considered: [A, B, C]. Picked **B** because [reason]. Rejected A because [reason]; rejected C because [reason].

## 未決 (Open questions)

_Things you want Leader / User to confirm. Be specific. Block on these before final report if they're load-bearing._

- **{question}** — [specific question]. Default behavior I picked: [X]. Risk if I'm wrong: [impact].

How to update

• Update incrementally — write the entry as you make the decision, NOT in a batch at the end. The whole point is to capture context that fades.
• Keep entries terse but self-contained — one bullet should be readable months later without re-reading the diff.
• Cite spec sections by section number (§How.4.7) so Leader can verify against the source.
• Cross-link related entries if a 折衷 decision later becomes a 偏離.
• Don't duplicate the diff — the file is for context, not code listings.

Status transitions

• IN_PROGRESS — work ongoing; file may be edited any time.
• COMPLETE — work finished, ready for Leader review. Set this before reporting back.
• BLOCKED — work paused awaiting Leader/User answer to an §未決 item. Required when an open question is load-bearing.

Subagent dispatch contract (Leader-side)

When Leader dispatches a subagent matching the invoke criteria, the dispatch prompt MUST include:

Create meetings/{date}_{topic}.impl-notes.md at the start of your work using the agent-impl-notes-log skill format. Update it incrementally — design decisions, deviations, tradeoffs, open questions. Mark Status: COMPLETE before final report. Include the file path in your report.

Subagent's final report MUST link the impl-notes file. Leader reads it before merging the work to verify decisions match Leader's intent.

Anti-patterns

• Writing impl-notes at the end as a batch — defeats the purpose; you've already forgotten the context.
• Logging every minor edit — file is for decisions, not edit history. Trivial mechanical fixes belong in the commit, not here.
• Using this file instead of the phase meeting log — the two coexist. Phase log is summative, impl-notes is concurrent. Phase log gets archived when sealed; impl-notes can be referenced from the phase log.
• Sealing the file without resolving 未決 items — open questions must be answered (by Leader/User) or moved to a backlog before status flips to COMPLETE.

Related skills

• session-to-meeting-log: produces the post-hoc phase meeting log; the two artifacts pair.
• leader-developer-handoff-contract: defines the dispatch contract; impl-notes is one of its outputs.
• subagent-review-cycles: when a subagent's work returns for review, Leader reviews the impl-notes alongside the diff.