From 549e2f4295c858a35426f312de6fca4d7642b810 Mon Sep 17 00:00:00 2001 From: Daniel Lam Date: Tue, 11 Aug 2026 00:03:48 +0700 Subject: [PATCH 1/3] fix: close wave-protocol gaps around resume, seeding, and peer pulls A resuming controller must continue an unfinished wave from its recorded manifest instead of pinning a new base; cache seeding must target a nonexistent destination; dirty-worktree removal escalates instead of forcing; peer-pulled commits stay out of the pulling task's review-package commit list; and a stale peer pick (source task failed or changed) is dropped or held, never integrated. Handoffs reconstruct join status from the ledger's join and escalation records rather than expecting it in the manifest. --- skills/delivery-handoff/SKILL.md | 11 ++++--- skills/delivery-pipeline/SKILL.md | 2 +- .../references/worktree-wave-execution.md | 33 +++++++++++++------ 3 files changed, 30 insertions(+), 16 deletions(-) diff --git a/skills/delivery-handoff/SKILL.md b/skills/delivery-handoff/SKILL.md index f645821..5cf1a77 100644 --- a/skills/delivery-handoff/SKILL.md +++ b/skills/delivery-handoff/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-handoff description: This skill should be used when the user asks for "a handoff prompt", "a prompt for codex/grok/claude", "something I can paste into another agent", or wants to continue tracked work in a different tool — and at any phase boundary of the cmk:delivery-pipeline skill when the operator prefers a different agent for the next phase. -version: 0.2.0 +version: 0.2.1 --- # Delivery Handoff @@ -71,10 +71,11 @@ freely; completeness matters, sections don't): rule. For clusters: the issue → worktree/branch/base table plus where the orchestration plan lives and which wave is active. For a handoff mid-way through a phase-3 wave, additionally enumerate every live task - worktree — path, task branch, wave-base SHA, and join state (pending / - integrated / escalated), from the wave manifest in the ledger — and - state that task worktrees follow the wave protocol's retention rules, - never ad-hoc cleanup. + worktree — path, task branch, and wave-base SHA from the ledger's wave + manifest, plus each task's join status (pending / integrated / + escalated) reconstructed from the ledger's join and escalation records — + and state that task worktrees follow the wave protocol's retention + rules, never ad-hoc cleanup. 3. **Read first** — ordered absolute paths: the phase skill(s) to follow, the tracking contract (`cmk:delivery-workflow`), the context-efficiency reference, the receiver's runtime binding diff --git a/skills/delivery-pipeline/SKILL.md b/skills/delivery-pipeline/SKILL.md index d15787e..166d953 100644 --- a/skills/delivery-pipeline/SKILL.md +++ b/skills/delivery-pipeline/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-pipeline description: This skill should be used when the user asks to "work on", "deliver", "tackle", "pick up", or "implement" a tracker issue (TICKET-123), a list of issues, or a body of tracked work expected to finish without supervision — even if they never say "pipeline". Also use when handed a cluster of related issues, or a single issue whose surrounding cluster should be derived from tracker dependencies, expecting dependency-aware sequencing across worktrees. -version: 0.2.0 +version: 0.3.0 --- # Delivery Pipeline diff --git a/skills/delivery-pipeline/references/worktree-wave-execution.md b/skills/delivery-pipeline/references/worktree-wave-execution.md index ec0784f..1e85213 100644 --- a/skills/delivery-pipeline/references/worktree-wave-execution.md +++ b/skills/delivery-pipeline/references/worktree-wave-execution.md @@ -51,7 +51,11 @@ Tasks may share a wave only when all three hold: member task IDs, the wave-base SHA, and each task's worktree path and branch name. This manifest is what a crashed run resumes from — without it, a resuming controller cannot tell an already-integrated task from one - that was never dispatched. + that was never dispatched. A resuming controller MUST check the ledger for + an incomplete wave manifest before any dispatch step and continue that + wave from its recorded wave-base SHA — never re-snapshot or pin a new + base while a manifest's wave is unfinished — and MUST verify each + leftover task branch forks from that recorded base before resuming it. 3. **Create one worktree per task.** `git worktree add -b --task- `, under the runtime's native worktree area — never an ad-hoc path — with the @@ -82,8 +86,8 @@ Tasks may share a wave only when all three hold: so it starts warm: prefer a copy-on-write clone (`cp -c -R` on macOS/APFS, `cp --reflink=auto -R` on Linux — `auto` degrades to a plain copy on filesystems without reflink), fall back to a plain copy, and accept a cold - build only when copying is unattractive. Seed only into a destination that - does not exist yet: `cp -R` into an existing directory nests + build only when copying is unattractive. Seeding MUST target a destination + that does not exist yet: `cp -R` into an existing directory nests (`target/target/…`) instead of merging, silently leaving stale artifacts in charge — so a resumed worktree keeps the build state it already has and is never re-seeded. Seeding MUST happen while no build runs in the parent @@ -108,10 +112,15 @@ task number): this task's work out of a shared branch; its remaining job is the overflow check. Build the package with the repo's review-package script where one exists (per `phase-3-execution.md`), giving each task an explicit per-task - output path and the task's declared scope and commits, so edits outside - the declared scope are appended to the package for review and surfaced as - a distinct non-zero exit, which the controller MUST handle as a scope - violation — never as a generic failure to retry blindly. + output path and the task's declared scope and its own commits. Commits a + controller-recorded peer pull cherry-picked from another task stay out of + that commit list: they are the source task's work, reviewed in its own + package, and listing them under this task's disjoint scope would surface + as a false scope violation (the scope filter already keeps their content + out of the package body). Edits outside the declared scope are appended + to the package for review and surfaced as a distinct non-zero exit, which + the controller MUST handle as a scope violation — never as a generic + failure to retry blindly. 2. **Integrate — two moves, each from the worktree that owns the branch.** First, *inside the task worktree*, rebase the task branch onto the current ticket branch tip. Then, *from the ticket worktree*, advance the ticket @@ -137,8 +146,8 @@ task number): branch (its commits are reachable from the ticket branch, so the delete loses nothing — never delete the branch before the merge). If removal refuses because the worktree is dirty, that is unreported, uncommitted - work — escalate to the worker's fix round instead of forcing; `--force` - is reserved for explicit abandonment. A failed or escalated task MUST + work — the controller MUST escalate to the worker's fix round instead of + forcing; `--force` is reserved for explicit abandonment. A failed or escalated task MUST retain its worktree and branch for the fix round. `git worktree prune` runs at phase close. @@ -160,7 +169,11 @@ repeats if the controller has new WIP. and verify during A's rebase that the cherry-picked commits drop as patch-identical duplicates — if they survive (the patch drifted after the pick), treat it as a conflict and escalate rather than landing B's work - twice. Unmediated peer merging is prohibited — it recreates the + twice. If B fails, is escalated, or its work materially changes before its + own join, A's pick is stale: the controller MUST either rewrite A's task + branch to drop the picked commits (recorded in the ledger) or hold A's + join until B lands — never integrate A carrying commits whose source never + shipped. Unmediated peer merging is prohibited — it recreates the cross-contamination this protocol removes. ## Shared state has one writer From b0f20cb60a6986346c9f20807a74bccb7dc22165 Mon Sep 17 00:00:00 2001 From: Daniel Lam Date: Tue, 11 Aug 2026 00:03:48 +0700 Subject: [PATCH 2/3] feat: one code path across infra profiles Product, protocol, and core logic are profile-invariant; environment differences live only at named composition and materialization surfaces. Engineering principles state what that means per phase (spec, implement, review, evidence), and design guidance gains a profile-neutrality section. A repo's own infra-profile standard refines the rule. --- .../references/engineering-principles.md | 35 +++++++++++++++---- skills/design/SKILL.md | 2 +- skills/design/references/design-guidance.md | 27 +++++++------- 3 files changed, 45 insertions(+), 19 deletions(-) diff --git a/skills/delivery-pipeline/references/engineering-principles.md b/skills/delivery-pipeline/references/engineering-principles.md index 67ba987..0061fc2 100644 --- a/skills/delivery-pipeline/references/engineering-principles.md +++ b/skills/delivery-pipeline/references/engineering-principles.md @@ -114,6 +114,31 @@ bookkeeping follows the human-decision-boundary rules above. In an unattended run, consultation applies only when it was requested up front — otherwise decide and record. +## One code path across infra profiles + +Product, protocol, and core/shared logic are profile-invariant: identical +across the local development stack and every deployed environment, with +environment differences living only at named composition or +materialization surfaces. In this pipeline that means: + +- **Spec/plan:** every environment difference is placed at a named + composition or materialization surface (launcher, IaC, config and + secret delivery, credential source). A spec that puts an environment + conditional inside product/protocol/core code is reworked before + implementation. +- **Implementation:** prefer extending the local materialization of a + missing production element over branching the shared path around it. +- **Review:** audit for profile leakage into shared code the same way + other architectural boundaries are audited. +- **Evidence:** local-stack proof is the default execution evidence for + profile-invariant logic; environment-specific evidence is reserved for + the composition/materialization surfaces that own it. A shared-logic + defect first seen on a deployed environment is a parity failure to + root-cause, not a normal find. + +Where the repository declares its own infra-profile standard, that +standard refines this rule and takes precedence. + ## Production readiness Every change is designed, built, reviewed, and shipped as something that @@ -174,12 +199,10 @@ what you don't otherwise hand them does not exist for them. The role definition carries model, effort, and preloaded skills — superpowers skills are named inline by whichever phase needs them, not -chosen through a separate lookup. That leaves a delegation prompt only -five things to state: task and file scope disjoint from every concurrently -running subagent, skills to invoke by name, source identity or an -instruction to refresh it, stop/escalation conditions, and the evidence -artifact the subagent must write to scratch (what it read, ran, changed, -or found, with file:line traces). +chosen through a separate lookup. The delegation-prompt and return +contracts are owned by `references/context-efficiency.md` § Delegation +and returns; the required evidence artifact goes to scratch with what the +subagent read, ran, changed, or found, with file:line traces. A subagent result without its evidence artifact is rejected and re-run. Evidence, not elapsed time, is how a hollow run is detected. Verify diff --git a/skills/design/SKILL.md b/skills/design/SKILL.md index 5078794..2055a5e 100644 --- a/skills/design/SKILL.md +++ b/skills/design/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:design description: This skill should be used when the user asks "how should we build this", "design the backend", "update the architecture", "draft a system design", "create a feature spec", "spec out this feature", or discusses architecture, tech stack changes, component design, or infrastructure layout. Covers drafting, refining, or updating distilled design documents under docs/design/ — system-wide or per-feature — checking for conflicts with upstream requirements and recorded decisions. -version: 0.4.0 +version: 0.5.0 --- # Design diff --git a/skills/design/references/design-guidance.md b/skills/design/references/design-guidance.md index 1e1d6d6..04c7515 100644 --- a/skills/design/references/design-guidance.md +++ b/skills/design/references/design-guidance.md @@ -16,6 +16,18 @@ Implementation-agnostic never means vague: the spec must be thorough and detailed enough that two independent implementations would agree on behavior — and specific enough to disagree with. +## Profile neutrality + +Mechanisms are specified once, neutral to the infrastructure environment +that will run them. Environment differences (local stack vs cloud +environments) appear only in composition and topology sections as +materialization choices — which launcher assembles the parts, which plane +delivers config and secrets, which infrastructure declares the boundary. A +design that forks product, protocol, or core behavior per environment is a +defect: push the difference down to a composition surface or redesign. +Where the repository declares its own infra-profile standard, that +standard refines this rule and takes precedence. + ## What the document must accomplish Whatever its shape, a reader must be able to extract: @@ -35,18 +47,9 @@ Whatever its shape, a reader must be able to extract: ## Design levels -Design is layered, and each layer is its own doc (or tree): - -- **System-wide** — the whole platform: layers, dependency direction, - component map, composition of sub-systems. -- **Sub-system / track** — one product line or major component: its - responsibilities, protocols, and how it composes the shared core without - leaking into it. -- **Feature-level** — one feature: scope, flows (success and failure), - boundaries, acceptance criteria when "done" isn't obvious. - -Lower levels reference upward and never silently contradict the level above; -a conflict is surfaced and resolved at the higher level. +Design is layered, and each layer is its own doc (or tree); the level +definitions and the never-silently-contradict rule live in +`references/design-conventions.md` § Design Levels. ## Multi-doc design trees From 9cbf4279d362a9bece5d7ad699ce40ccf1c310d3 Mon Sep 17 00:00:00 2001 From: Daniel Lam Date: Tue, 11 Aug 2026 00:03:48 +0700 Subject: [PATCH 3/3] docs: deduplicate skill guidance onto single owners Give each cross-file contract one owning file and reduce other mentions to a pointer: delegation-prompt shape (context-efficiency), ADR supersession (adr-conventions), learn entry format (learn-template), design levels (design-conventions), spec-plan freshness (context- efficiency capsule rules), AC dispositions (acceptance-criteria). Trim in-file repetition in codebase-docs and discover-efforts without dropping any rule. --- skills/adr/SKILL.md | 4 +-- skills/codebase-docs/SKILL.md | 29 +++---------------- skills/delivery-spec-plan/SKILL.md | 13 ++++----- skills/delivery-workflow/SKILL.md | 7 ++--- .../design/references/design-conventions.md | 4 ++- skills/discover-efforts/SKILL.md | 7 ++--- skills/learn/SKILL.md | 2 +- skills/learn/references/learn-conventions.md | 10 +------ 8 files changed, 21 insertions(+), 55 deletions(-) diff --git a/skills/adr/SKILL.md b/skills/adr/SKILL.md index b7543fc..ec1b0d8 100644 --- a/skills/adr/SKILL.md +++ b/skills/adr/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:adr description: This skill should be used when the user asks to "record this decision", "we decided to use X over Y", "document why we chose this approach", "record an ADR", "update ADR-0003", or needs to create or update architecture decision records for system-level technical choices like choosing a database, communication protocol, or infrastructure pattern. -version: 0.3.0 +version: 0.3.1 --- # ADR @@ -26,7 +26,7 @@ Read `references/adr-conventions.md` for placement and lifecycle rules and `refe 1. Read the existing ADR in full. 2. **Upstream check:** If a relevant design doc exists under `docs/design/`, check whether the revised decision conflicts with current architecture. Warn the user if so. 3. A decision that *evolves without changing direction* updates in place: refine consequences, note what shifted and why. Move `Proposed` → `Accepted` when the team agrees. -4. A decision that *changes direction* is a new ADR: write the replacement under its own number, mark the old record `Superseded by NNNN`, and link forward. Never delete or rewrite a superseded ADR — the history stays readable. Partial supersession is stated on the old record ("the X portion superseded by NNNN") rather than pretending the whole decision flipped. +4. A decision that *changes direction* is a new ADR under its own number; the supersession mechanics — forward links, partial supersession, never deleting or rewriting the old record — follow `references/adr-conventions.md` § Lifecycle. 5. Refresh the index one-liners for every record the change touched. ## Output diff --git a/skills/codebase-docs/SKILL.md b/skills/codebase-docs/SKILL.md index be0920e..b918a91 100644 --- a/skills/codebase-docs/SKILL.md +++ b/skills/codebase-docs/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:codebase-docs description: Generate or update hierarchical, AI-navigable documentation for a codebase under `docs/ai/`. Use whenever the user asks to "document the codebase for AI", "bootstrap AI docs", "generate codebase map", "set up AI navigation docs", "update AI docs", "refresh docs after change", or mentions building progressive-disclosure docs so an AI can find the right source files quickly. Produces a tree of concise docs that *point to* code rather than duplicate it. Use even when the user only says "document this repo" without specifying the structure. -version: 0.1.0 +version: 0.1.1 --- # Codebase Docs for AI Navigation @@ -71,7 +71,7 @@ Use a named symbol when one exists — function, class, struct, type, const, rou **Coherence over splitting.** If a topic is naturally one story, keep it in one doc even if it runs a bit long. Only split when there's a genuinely bounded sub-concept *and* the parent is getting unwieldy — see the split heuristic below. -**Match the code's vocabulary.** Use the same names the code uses. If the source folder is `rcp/` (or the package is `@org/rcp`, or the module is `rcp`), the doc folder is `rcp/` — not a more "descriptive" alias like `remote-control-protocol/`. The doc's job is to be findable from the code's own terms. +**Match the code's vocabulary.** Use the same names the code uses (the folder-naming rule under "Output location and shape") — the doc's job is to be findable from the code's own terms, never through a more "descriptive" alias. ## Split heuristic @@ -122,27 +122,7 @@ Rule of thumb: a good branch doc is ~30–80 lines. A good leaf doc is ~20–120 ## Working example (sketch) -The shape is the same regardless of stack — the folder names just mirror whatever the codebase calls its parts. A typical tree for a multi-area repo: - -``` -docs/ai/ -├── README.md # one paragraph: what the repo is + a menu of areas -├── / -│ ├── README.md # menu of sub-topics in this area -│ ├── .md # leaf: what / (why) / where -│ ├── .md -│ └── / -│ ├── README.md -│ └── .md -├── / -│ ├── README.md -│ ├── .md -│ └── .md -└── / - └── README.md # small enough to stay single-doc -``` - -Concrete shape examples for different stacks: +The shape is the same regardless of stack — the tree under "Output location and shape" above, with folder names mirroring whatever the codebase calls its parts. Concrete shape examples for different stacks: - **TS monorepo (`apps/`, `packages/`)** — top-level menu mirrors workspace members: `docs/ai/apps//`, `docs/ai/packages//`. - **Rust workspace (`crates/`)** — top-level menu mirrors crate names: `docs/ai//`. @@ -179,8 +159,7 @@ That's the whole doc — ~15 lines, three clear hooks into the code, no copied s - **Paraphrased code.** If the doc is explaining control flow line-by-line, delete that and just point to the function. - **Essay-style prose.** Bullets and short paragraphs beat flowing prose for skim-reading. - **Phantom references.** Never invent a function or file name. If you're unsure, open the file and check. -- **Over-splitting.** Eight three-line leaves are harder to navigate than one thirty-line doc. Err toward keeping related things together. -- **Under-splitting.** A single 500-line `README.md` with everything is exactly what this skill is trying to replace. +- **Over- or under-splitting.** Apply the split heuristic; both directions are covered there. - **Documenting aspirations.** Only describe what's in the code now. ## Final check before finishing diff --git a/skills/delivery-spec-plan/SKILL.md b/skills/delivery-spec-plan/SKILL.md index 16b1ff0..dbf7ea5 100644 --- a/skills/delivery-spec-plan/SKILL.md +++ b/skills/delivery-spec-plan/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-spec-plan description: This skill should be used when the user asks for a "spec", "design", "implementation plan", or "how should we build this" for a tracker issue, after context intake for any non-trivial change, and as phase 2 of the cmk:delivery-pipeline skill. -version: 0.2.0 +version: 0.2.1 --- # Delivery Spec & Plan @@ -26,10 +26,9 @@ the record; durable conclusions reach `docs/design/`, `docs/decisions/`, the tracker, and the PR description. Read `cmk:delivery-workflow` and `cmk:delivery-pipeline`'s context-efficiency -reference before relying on the intake brief. Refresh mutable tracker, -code-host, repository HEAD, and ancestry inputs before planning when their -recorded source identity is no longer proven current — an intake brief -cannot authorize planning after continuity, scope, or provenance is lost. +reference before relying on the intake brief — the brief is a capsule, and +the context-efficiency continuity rules decide when mutable inputs must be +refreshed before planning on them. Apply `cmk:delivery-pipeline`'s engineering-principles reference throughout: decide everything yourself, staff-level bar without overengineering, existing @@ -127,9 +126,7 @@ them — an AC with no task is a hole in the plan, and so is a surface-inventory item with no covering task. Planning is the cheapest moment to find out a criterion will not land: if no task can honestly satisfy one, take its disposition now, on the issue, per `cmk:delivery-workflow`'s -`references/acceptance-criteria.md`. A criterion carried into implementation -on the hope it works out becomes a ship-time surprise, which is the same -decision made later with worse options. +`references/acceptance-criteria.md`. A plan whose tasks all serialize on one file is worth re-partitioning before it executes; sequential-by-accident is different from sequential-by-necessity, diff --git a/skills/delivery-workflow/SKILL.md b/skills/delivery-workflow/SKILL.md index c80d3ca..2cc5fbf 100644 --- a/skills/delivery-workflow/SKILL.md +++ b/skills/delivery-workflow/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:delivery-workflow description: This skill should be used when the user asks to "start tracked work", "reconcile the tracker", "check if this is ready to ship", "keep the issue useful", or "check acceptance criteria" — or needs the tracking contract every other delivery skill operates inside. -version: 0.2.0 +version: 0.2.1 --- # Delivery Workflow @@ -121,10 +121,7 @@ Using Linear as your tracker? Read `references/linear.md`. | Splitting PR review across the issue and the PR | Keep it on one surface — the PR or the tracker's synced review thread | | Copying a deferred finding into several places | Link the review thread and the new follow-up issue | | Treating merge as delivery | Verify acceptance before the done state | -| Leaving the AC checklist untouched all run | Tick each criterion as its proof lands, evidence reachable | -| Checking a criterion because it feels done | Check it only against reachable proof; intent is not evidence | -| Shrinking the AC to match what got built | Rescope explicitly, move removed criteria to a tracked successor, say why | -| Delivering a narrow slice under a broad AC | Rewrite the AC to the honest outcome and track the remainder | +| Shrinking the AC to match what got built | Rescope explicitly: successor tracked, description rewritten, reason recorded (`references/acceptance-criteria.md`) | | Trusting only auto-linking | Keep the issue ID in the branch and the PR body | | Treating the template as a form | Use any clear structure that serves the same review goals | | Claiming tests passed without proof | Include reproducible automation and its passing result | diff --git a/skills/design/references/design-conventions.md b/skills/design/references/design-conventions.md index 5e3752f..638a2a9 100644 --- a/skills/design/references/design-conventions.md +++ b/skills/design/references/design-conventions.md @@ -13,7 +13,9 @@ - **System-wide** — the whole platform: layers, dependency direction, component map, sub-system composition. -- **Sub-system / track** — one product line or major component. +- **Sub-system / track** — one product line or major component: its + responsibilities, protocols, and how it composes the shared core without + leaking into it. - **Feature-level** — one feature, scoped by a `Scope:` header. - Lower levels reference upward and never silently contradict the level above; conflicts are surfaced and resolved at the higher level. diff --git a/skills/discover-efforts/SKILL.md b/skills/discover-efforts/SKILL.md index a21a945..42dc772 100644 --- a/skills/discover-efforts/SKILL.md +++ b/skills/discover-efforts/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:discover-efforts description: This skill should be used when the user asks to "discover the delivery efforts here", "audit this body of work before we file issues", "reconcile these prompts, requirements, designs, or code against the tracker", "figure out what issues we actually need before starting", or hands over an uncertain body of work that needs a reconciled tracker issue set before delivery begins. -version: 0.1.0 +version: 0.1.1 --- # Discover Efforts @@ -82,9 +82,8 @@ relations. ## Exit and hand off -Before exit, reconcile every affected issue and relation, then read back -exact IDs, descriptions or changed fields, statuses, estimates, parents, -children, blockers, related issues, and duplicate dispositions. +Before exit, reconcile every affected issue and relation and read every +write back. Return an exit report with: source identities and completeness; each ledger row's outcome, classification, matching coverage, and action; every diff --git a/skills/learn/SKILL.md b/skills/learn/SKILL.md index 6a249c6..9c7dcf7 100644 --- a/skills/learn/SKILL.md +++ b/skills/learn/SKILL.md @@ -1,7 +1,7 @@ --- name: cmk:learn description: This skill should be used when the user asks to "remember this", "save this learning", "capture the key findings", "what do we know about X", "save that gotcha", or needs to extract and record non-obvious learnings, gotchas, and valuable knowledge from conversations, research sessions, debugging, files, or user instructions. -version: 0.2.0 +version: 0.2.1 --- # Learn diff --git a/skills/learn/references/learn-conventions.md b/skills/learn/references/learn-conventions.md index 6184d5f..b61aa04 100644 --- a/skills/learn/references/learn-conventions.md +++ b/skills/learn/references/learn-conventions.md @@ -27,15 +27,7 @@ Teams define their own topics based on what they're working on. ## Entry Format -Each entry follows this structure: - -```markdown -### [Clear, specific title] -- **Date:** YYYY-MM-DD -- **Context:** [Where this came from — session, debugging, PR, incident, etc.] -- **Learning:** [The insight itself — concise and actionable] -- **Applies to:** [Downstream tags — e.g., design, deployment] -``` +Each entry follows the structure in `references/learn-template.md`. ## Conflict Resolution