Skip to content

Plan Archive Harvest

This document records what was extracted from the 16 plan files in plans/ (working copy of ~/.claude/plans/ in the source) for inclusion in the public documents in docs/. The plan files themselves are not mirrored here — they are an internal engineering ledger; only their public-relevant content is folded into the appropriate docs.

The harvest follows the user-chosen "pragmatic" strategy: read each plan, identify content not covered in non-plan docs, fold it where it belongs. Plan files in the source repo remain unchanged.

Coverage matrix

For each plan, this table records:

  • whether it contributed material to a public document, and
  • whether the public version captures the operationally-relevant content the plan held.

Legend: * + — content was harvested into the public docs. * = — content already covered in the consolidated docs; plan is redundant for the public surface. * m — maintainer-only material; left in the plan archive (acknowledged in maintainer/adr/README.md candidates list). * · — superseded plan; no harvest needed.

Plan Outcome Where harvested
der-offset-mode-in-szenen-serialized-quilt.md (active project-wide audit) =, m Most operator+contributor content already in OPERATOR_GUIDE / DEVELOPER_GUIDE / ARCHITECTURE / PROTOCOL. ADR candidates lifted to maintainer/adr/README.md.
hi-claude-i-am-lively-pancake.md (architecture review P0–P3) =, m Recurring architecture rules already in ARCHITECTURE; "single state lock" + "exclusive USB ownership" added to ADR candidates list.
scene-manager-feature.md = The on-disk scene file format is now in reference/SCENE_FORMAT.md.
in-der-aktuellen-fassund-linked-karp.md (Scene Manager bugfix sweep) · Bug fixes shipped; no public-doc impact.
der-offset-mode-szenen-hierarchie.md · Superseded by the Phase-D scene refactor; the canonical scene shape is in reference/SCENE_FORMAT.md.
der-offset-mode-formula-modes-followup.md = The OPC_OFFSET tagged-union shape is documented in PROTOCOL. The five offset-modes are in OPERATOR_GUIDE §6a and re-listed in reference/SCENE_FORMAT.md.
seit-den-letzten-nderungen-sleepy-wolf.md (cyclic-effect phase-lock) + Folded a short operator-friendly note into TROUBLESHOOTING.md, wled/OPERATOR.md and the GLOSSARY entry "Strip timebase / strip.now". See "Cyclic-effect phase-lock" below for the full content.
flag-handling-unification-and-scene-editor.md = The flags-byte canonical builder is documented in PROTOCOL §"Flags byte" and GLOSSARY. Part 2 (scene editor) was superseded by scene-manager-feature.md.
plane-f-r-mich-ein-refactored-boole.md (OPC_CONTROL design) = The OPC_CONTROL body layout is in PROTOCOL §"OPC_CONTROL". Historical OPC_CONTROL_ADV / P_ControlAdv naming is purely internal-history.
effect-vs-preset-terminology-cleanup.md + Terminology decisions folded into GLOSSARY (the "Preset" and "Effect" entries). The classification of A1–A12 / B1–B2 is internal-history and remains in the plan archive.
du-hast-f-r-mich-witty-crystal.md (selective UI updates) = The state-scope tokens are documented in ARCHITECTURE §"UI Scope Matrix" and reference/SSE_CHANNELS.md.
gateway-lifecycle-ui-signals.md = Banner + master-pill design is documented in OPERATOR_GUIDE §"Master pill states" and PROTOCOL §"Gateway state machine".
analyse-the-wled-effect-adaptive-allen.md (smarter OTA failure handling) = The OTA-gate matrix is in DEVELOPER_GUIDE §"WLED OTA gate matrix"; failure modes in OPERATOR_GUIDE. The plan's deeper rationale (D.1–D.5 firmware-side options) is preserved in DEVELOPER_GUIDE.
swirling-bubbling-pike.md (OLED rendering on Core-0) m Firmware-internal performance change; no operator or contributor doc impact. Stays in the plan archive.
mache-einen-genauen-diff-splendid-sunbeam.md (sync three files between WLED fork and standalone repo) m Operational maintenance task. No public-doc impact.
plans/README.md · The plan index itself; not a candidate for public publication.

Substantive harvested content

The plans contributed two pieces of public-relevant content that were not previously documented anywhere outside the plan archive.

Cyclic-effect phase-lock under offset mode

Source plan: seit-den-letzten-nderungen-sleepy-wolf.md (German title: "RaceLink Offset-Mode: Phase-Lock bei zyklischen Effekten beheben" — "RaceLink offset mode: fix phase lock on cyclic effects").

Background. When using offset mode with a cyclic WLED effect — one whose pixel output is a direct function of strip.now (Breathe via sin16_t(strip.now * speed), Pacifica via beatsin*_t, etc.) — the start-stagger works but each node reaches the same point of the cycle simultaneously. The visible result: every node hits maximum brightness at the same time, so the "wave" effect collapses to a synchronous pulse.

Why. The host's offset-mode dispatch staggers when the effect starts (per-device deferred apply). It does not also shift the time base the effect runs against. Because all devices share the same strip.timebase (the master-aligned time received in OPC_SYNC), and because Breathe's render is f(strip.now) only, every device computes the same brightness curve at the same wall time.

State-machine effects (Traffic Light, Color Wipe, Scan) are unaffected because their phase is relative to the per-device SEGENV.step start time, which the offset does shift.

Fix. A persistent per-device phase offset on strip.timebase, re-asserted after every SYNC. The WLED usermod maintains:

  • activePhaseOffsetMs — the currently-active per-device phase shift (set when an effect is applied via the offset-mode path, cleared when a non-offset effect is applied);
  • pendingDeferredOffsetMs — captured at deferral time so serviceDeferredApply() can update activePhaseOffsetMs consistently.

After every OPC_SYNC the firmware:

  1. Computes the drift error against the logical (master-aligned) timebase, i.e. (int32_t)strip.timebase + activePhaseOffsetMs. Without this, a non-zero activePhaseOffsetMs would always look like an err == activePhaseOffsetMs and trigger endless hard-resyncs.
  2. Applies the drift correction to strip.timebase.
  3. Re-asserts the offset by subtracting activePhaseOffsetMs from strip.timebase. This makes the device's strip.now run that many milliseconds behind master — which produces the desired phase shift in any time-based effect.

Operator-visible content. Folded into:

Implementation detail (for firmware contributors): the applyPhaseOffsetToTimebase() helper subtracts activePhaseOffsetMs from strip.timebase and is called after every strip.timebase write (drift correction, hard resync, inline-apply, deferred-apply). The drift-correction error is computed against strip.timebase + activePhaseOffsetMs — i.e. the logical timebase as if the offset were zero — so the correction tracks master-relative drift, not the offset itself.

Effect vs. Preset terminology cleanup

Source plan: effect-vs-preset-terminology-cleanup.md.

Background. After the Phase-D rename of OPC_CONTROL → OPC_PRESET and OPC_CONTROL_ADV → OPC_CONTROL, plus the P_StatusReply.presetId → effectId rename, the protocol now cleanly distinguishes:

Concept Wire Carries
Preset OPC_PRESET (0x04, fixed 4 B) a WLED preset slot ID
Effect (segment mode) OPC_CONTROL (0x08, variable 3..21 B) direct effect parameters: mode, speed, intensity, custom sliders, palette, colours
Effect ID readback P_StatusReply.effectId the active WLED segment mode index

The rename surfaced an older problem: the codebase used "effect" generically for the WLED-preset dropdown in several places, predating the protocol cleanup.

Outcome. The cleanup plan classifies each occurrence as one of:

  • Category A — pure misnaming (no logic bug, but actively misleading). Renaming is a normal refactor.
  • Category B — bug-risk. Future maintainer reading the name literally could pass a WLED effect-mode index where a preset ID is expected. Cleared up.
  • Category C — legitimate "effect" usage. No change.

Operator/contributor-visible content. Folded into GLOSSARY.md — the "Preset" and "Effect" entries explicitly call out the dual meaning and the disambiguation.

The internal-history catalogue (A1–A12, B1–B2) is purely a maintenance trace and is left in the plan archive.

What was deliberately NOT harvested

  • Threading-fix internals (A-series of the project-wide audit). The locking rules are documented in host/ARCHITECTURE.md; the per-finding trace and regression-test history is maintainer material.
  • Bug-fix sweeps (B-series) — the resulting code is shipped; the sweep narrative is maintainer material.
  • C-series UX findings — implementations are visible in the current OPERATOR_GUIDE / UI_CONVENTIONS / DEVELOPER_GUIDE.
  • D-series doc-gap findings — mostly already shipped as OPERATOR_GUIDE / DEVELOPER_GUIDE / PROTOCOL / etc. The remaining D-series gaps are addressed by this consolidation (see AUDIT_RESPONSE.md).
  • OLED-rendering offload to Core-0 — pure firmware performance optimisation; no operator or contributor surface.
  • WLED-fork-vs-standalone-repo file-sync plan — operational maintenance.