Agent impl notes log
Skill wei18/apple-dev-skills/collaboration-skills/skills/agent-impl-notes-log
Reusable Claude Code skills for AI-agent-driven Swift / Apple-platform development — composable via git submodule; aggregates other specialist skill repos
npx -y skills add wei18/apple-dev-skills --skill agent-impl-notes-logAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Maintain a running `meetings/{date}_{topic}.impl-notes.md` *during* subagent task execution to capture in-flight design decisions, intentional deviations from spec, considered alternatives, and open questions for Leader/User. Distinct from the post-hoc phase meeting log; this file is updated incrementally as decisions are made. Invoke at the start of any non-trivial subagent dispatch, when ambiguity is encountered mid-task, or when about to deviate from spec.
SKILL.md
5.5 KB, as published. Nobody here has run it
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.,
// UNCONFIRMEDmarkers, "Unconfirmed ?" prerequisites). - Introduces a new dependency, target, or module.
- Refactors existing code beyond a one-line fix.
- Any task with a
PROPOSAL_DRAFTstep 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.mdat the start of your work using theagent-impl-notes-logskill format. Update it incrementally — design decisions, deviations, tradeoffs, open questions. MarkStatus: COMPLETEbefore 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.