notetaker-fundamentals

Leave structured AI development notes above complex functions and decision points. AI-DEV-NOTE annotations preserve rationale, trade-offs, and context—such as why a caching strategy was chosen—so AI tools and future developers understand the reasoning behind implementation choices without reconstructing it from git history.

Structured TODOs go beyond task names: include the problem being deferred, related issues or PRs, and constraints or alternatives considered. This context-rich format helps AI assistants and team members understand not just what remains, but why it was deferred and what decision criteria apply.

Uncertainty markers signal unresolved questions, experimental approaches, or areas where trade-offs remain. They guide AI assistants to recognize unstable sections and avoid propagating assumptions downstream, improving traceability and enabling more informed refactoring decisions.

Embed issue and PR references directly in AI development notes and enhanced TODO comments. Cross-linking creates breadcrumbs that connect code annotations to external context—requirements, discussions, and decisions—making the rationale discoverable without leaving the codebase.

Yes. The Skill enforces cross-language comment formats and proximity guidelines so annotations remain consistent whether you're writing Python, JavaScript, Go, or other languages. Standardized placement and syntax ensure AI tools and human readers find and interpret notes reliably.