Revise *.instructions.md: separate AI-relevant special knowledge from background information for contributors

[softhack007]

Revising AI review instructions:

• Reduce context window use for AI review tools, by avoiding repeating common knowledge and API information that is (usually) part of the AI training datasets any way.
• Introduce a mechanism to maintain both parts in single files, to avoid "silent diversion" over time
• Adding a coderabbit path instruction that ensures cross-checking of both parts whenever a PR modifies instruction files

Objectives:

• Primary Goal: only inject content in AI-visible areas that are WLED-MM–specific or which deviate from general knowledge (the context window "token cost" of true false-positive suppressors is always worth it).
• Soft goal: keep each file's AI-facing section lean enough that the signal-to-noise ratio in the attention layer stays high — around 1,500–2,000 words per file type is a reasonable practical ceiling for current models.
• Aspirational: 500 words per file if achievable without sacrificing review quality.

This is an evolution of #353, based on the discussion in #353 (comment):

---

Large language models already have extensive general knowledge about C++, ESP-IDF, GitHub Actions, etc. The genuine value of instruction files is narrow but real:

What AI genuinely doesn't know without you telling it	What AI already knows well enough
Your project's intentional deviations from general best practice	General C++ / ESP-IDF / GitHub Actions patterns
Decisions that look like bugs but aren't (e.g. a float→int→uint8_t wrapping pattern)	Standard style rules
Which files/patterns to ignore or treat as deprecated	Common security practices
Your PR process expectations	How delay() works in FreeRTOS
Project-specific macro semantics (WLEDMM_FASTPATH, d_malloc)	Memory allocation tradeoffs
Which reviewer comments are out of scope for this PR	Naming conventions

The key insight: instruction files are most valuable when they prevent false positives (AI flagging intentional patterns as bugs) and encode decisions that can't be inferred from the code alone.

---

Guidelines for Efficient Instruction File Setup

1. Only document what can't be inferred from the code or from general training.
   If the AI would get it right without instruction 95% of the time, the instruction probably isn't worth the token cost.

2. Prefer short, actionable rules over explanations.
   "Do not flag uint8_t x = int(f) as a bug when the comment says // float→int wrapping" is more useful than a paragraph explaining why. The paragraph is for humans; the rule is for AI.

3. Keep the total injected instruction size per file type under ~500 words.
   Beyond that, the marginal value of additional instructions drops rapidly and the distraction cost rises.

4. Encode "false positive suppressors" first, feature guidance second.
   "Don't flag pattern X as a bug" is more impactful than "always do Y" because it directly prevents noise.

5. Treat instruction files like tests — they need maintenance when the code changes.
   If you wouldn't update the instruction file when refactoring the relevant code, don't write the instruction.

---

Bottom line: The sweet spot is a short general file covering project identity + a handful of false-positive suppressors for your project's intentional deviations, with automated tooling doing the heavy lifting for everything else. More is not better.

Summary by CodeRabbit

• Documentation

  • Marked many reference sections as human-only background for reviewers and clarified platform/PSRAM and migration guidance; refined wording across coding examples and guidance to reduce ambiguity.

• Chores

  • Added review guidance to detect and flag drift between AI-facing rules and HUMAN-only examples, treating missing HUMAN-only updates as advisory; minor formatting cleanup.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added AI-review guidance and HUMAN-only comment blocks: .coderabbit.yaml gained reviews.path_instructions for ".github/*.instructions.md" requiring checks for contradictions between <!-- HUMAN_ONLY_START -->...<!-- HUMAN_ONLY_END --> blocks and AI-facing rules; several .github/*.instructions.md files were wrapped and had wording edits.

Changes

Cohort / File(s)	Summary
CodeRabbit config ​.coderabbit.yaml	Added reviews.path_instructions for ".github/*.instructions.md" to require AI reviewers to detect contradictions between <!-- HUMAN_ONLY_START -->...<!-- HUMAN_ONLY_END --> blocks and AI-facing rules when those files are modified; missing HUMAN-only updates are suggested (non-mandatory). Trailing newline removed.
GitHub instruction files ​.github/cicd.instructions.md, ​.github/cpp.instructions.md, ​.github/esp-idf.instructions.md, ​.github/copilot-instructions.md	Wrapped many contributor/reference sections in <!-- HUMAN_ONLY_START -->/<!-- HUMAN_ONLY_END -->, added top-level notes for AI review tooling, and applied targeted wording edits (VLA/FreeRTOS wording, const/constexpr guidance, hot‑path phrasing, RISC‑V shift notes, PSRAM/IDF caveats, contributor guidance). Documentation-only edits.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Revise copilot-instructions.md: consolidate, shorten, and extract language-specific rules, take 2 #353: Similar edits to .coderabbit.yaml path_instructions and wrapping .github/*.instructions.md content in HUMAN-only comment blocks.

Suggested reviewers

• netmindz

Poem

🐰 I hopped through docs with nimble paws,

I tucked the human bits behind soft laws,
AI reads rules while I mind the seam,
Examples safe in a quiet dream,
Carrots for reviewers — tidy and clean.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main objective of the PR: separating AI-relevant rules from contributor background information in instruction files using HUMAN_ONLY markers.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch copilot_instructions_v2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== .github/cpp.instructions.md (with line numbers) ==="
cat -n .github/cpp.instructions.md
echo ""
echo "=== .github/esp-idf.instructions.md (with line numbers) ==="
cat -n .github/esp-idf.instructions.md
echo ""
echo "=== .github/cicd.instructions.md (with line numbers) ==="
cat -n .github/cicd.instructions.md
echo ""
echo "=== .github/copilot-instructions.md (with line numbers) ==="
cat -n .github/copilot-instructions.md

Length of output: 85785

---

@softhack007 — here's a file-by-file breakdown with exact line ranges, disposition, and replacement rule text.

---

cpp.instructions.md — Proposed cuts

Block 1 · Lines 112–127 — const rationale + locals example

Action: Move to HUMAN_ONLY. Replace with one-line rule.

Add `const` to cached locals in hot-path code (helps the compiler keep values
in registers). Pass and store objects by `const&` to avoid copies in loops.

---

Block 2 · Lines 143–171 — constexpr over #define + `static_assert over `#error

Action: Move both subsections to HUMAN_ONLY. Replace with two-line rule.

Prefer `constexpr` over `#define` for typed constants (scope-safe, debuggable).
Use `static_assert` instead of `#if … `#error`` for compile-time validation.
Exception: `#define` is required for conditional-compilation guards and
build-flag-overridable values.

---

Block 3 · Lines 175–189 — const member function rationale bullets

Action: Move the "Benefits for GCC/Xtensa/RISC-V" bullet list (Lines 184–188) to HUMAN_ONLY. Keep Lines 175–183 (the rule + code example) and Line 189 (the mutable note) as AI-facing.

No replacement rule needed — the retained text already encodes the actionable rule.

---

Block 4 · Line 107 — VLA explanation (inline prose, ~100 words)

Action: Replace the long inline explanation with a condensed rule; move the rationale to HUMAN_ONLY.

Condensed AI-facing rule:

**Avoid Variable Length Arrays (VLAs)**: FreeRTOS task stacks are typically
2–8 KB. A runtime-sized VLA can silently exhaust the stack.
Use fixed-size arrays or heap allocation (`d_malloc` / `p_malloc`).
Any VLA must be explicitly justified in source or PR.

---

Block 5 · Lines 219–221 — Hot-path intro paragraph

Action: Move to HUMAN_ONLY. It names the file pipeline (general orientation text), not a reviewable rule.

No replacement needed — the section heading is sufficient context.

---

Block 6 · Lines 289–313 — "Avoid Nested Calls — Fast Path / Complex Path"

Action: Move the code examples (Lines 293–308) to HUMAN_ONLY. Keep Lines 289–292 (rule description) and Lines 310–313 (the three bullet summary) as AI-facing.

Condensed AI-facing rule (replaces examples):

Hoist per-frame decisions (e.g. simple vs. complex segment) out of the per-pixel
loop. Keep fast-path functions free of non-inline calls, multi-way branches, and
complex switch-case decisions. Code duplication between fast/slow variants is
acceptable to keep the fast path lean.

---

Block 7 · Lines 315–329 — "Function Pointers to Eliminate Repeated Decisions"

Action: Move the code example (Lines 322–327) and the image_loader.cpp explanation to HUMAN_ONLY. Keep the principle statement (Lines 315–317) as AI-facing.

Condensed AI-facing rule:

When the same per-frame decision (e.g. "which drawing routine?") would be
re-evaluated per pixel, assign the chosen variant to a function pointer once
per frame and call through the pointer in the inner loop.

---

Block 8 · Lines 394–408 — "Bit Shifts Over Division"

Action: Move the code example and unsigned-sign warning (Lines 400–408) to HUMAN_ONLY. Keep the platform note and rule summary as AI-facing.

Condensed AI-facing rule:

On RISC-V targets (ESP32-C3/C6/P4), prefer explicit bit-shifts for power-of-two
arithmetic — the compiler does **not** always convert divisions to shifts on
RISC-V at `-O2`. Always use unsigned operands; signed right-shift is
implementation-defined.

---

Estimated savings for cpp.instructions.md

Block	Lines	Words freed
1 — const rationale + locals example	112–127	~130
2 — constexpr + static_assert	143–171	~165
3 — const member rationale bullets	184–188	~75
4 — VLA explanation (condensed in-place)	107	~70
5 — Hot-path intro	219–221	~40
6 — Fast/slow path code examples	293–308	~130
7 — Function pointer code + explanation	318–329	~100
8 — Bit shifts code + sign warning	400–408	~90
Total		~800 words

Current AI-facing: 2 791 words → projected: ~1 990 words (29% reduction). Still above 500 but this is the set that carries zero review-quality risk.

---

esp-idf.instructions.md — Proposed cuts

This is the highest-value file to trim (3 897 AI-facing words).

Block A · Lines 196–273 — "Compiler changes" + "C++ language features GCC 8→14"

Action: Move entirely to HUMAN_ONLY. These are general GCC/C++ changelog tables an LLM already knows. The only WLED-MM-specific constraint worth keeping AI-facing is:

Do **not** use C++20 features without a `#if __cplusplus > 201703L` guard —
WLED-MM must still build on IDF v4.4 (GCC 8.4, C++17). Mark migration TODOs
with `// TODO(idf5):`.

This saves approximately ~430 words (the single largest block in the entire file).

---

Block B · Lines 165–175 — "Key ESP-IDF version thresholds" table

Action: Move to HUMAN_ONLY. This is general ESP-IDF changelog. Retain only the actionable rule from Lines 177–188 (comment explaining the guard + range guard example).

No replacement rule needed — the guard example already states what matters.

Saves ~90 words.

---

Block C · Lines 277–288, 290–301 — RMT and I2S v4→v5 API tables (the tables only, not WLED impact lines)

Action: Move the table rows to HUMAN_ONLY. Keep Lines 288 ("WLED impact: NeoPixelBus + IR use legacy RMT…") and the equivalent WLED impact note in I2S AI-facing.

Condensed AI-facing rules:

**RMT**: NeoPixelBus LED output and IR receiver use the legacy `rmt_*` API
removed in IDF v5. Do not introduce new legacy RMT calls. See HUMAN_ONLY
section for the full v4→v5 API mapping.

**I2S**: The audioreactive `I2SSource` class uses the legacy
`i2s_driver_install()` API deprecated in IDF v5. When touching audio source
code, wrap any I2S init in `#if ESP_IDF_VERSION` guards. See HUMAN_ONLY
section for the migration pattern.

Saves ~110 words.

---

Block D · Lines 326–344 — ADC / SPI Flash / GPIO tables

Action: Move entirely to HUMAN_ONLY. These are standard ESP-IDF API renames that an LLM already knows. The actionable rule (use the compat shim, add version guards) is already captured by the migration checklist at Lines 368–374.

Saves ~80 words.

---

Block E · Lines 790–801 — "Quick Reference: IDF v4→v5 API Mapping" table

Action: Move entirely to HUMAN_ONLY. It duplicates information from the per-peripheral sections above.

Saves ~80 words.

---

Block F · Lines 34–47 — Build-target #elif code example

Action: Move the code snippet (Lines 37–47) to HUMAN_ONLY. Keep Lines 49–54 (the four guideline bullets) AI-facing — they are actionable rules that prevent false positives.

Condensed note above the bullets:

Gate chip-specific code with `#if defined(CONFIG_IDF_TARGET_*)` chains.
Do **not** use `CONFIG_IDF_TARGET_*` for feature detection — use `SOC_*`
capability macros instead (see next section).

Saves ~60 words.

---

Estimated savings for esp-idf.instructions.md

Block	Lines	Words freed
A — GCC/C++ changelog tables	196–273	~430
B — IDF version thresholds table	165–175	~90
C — RMT + I2S API tables	277–301	~110
D — ADC + Flash + GPIO tables	326–344	~80
E — Quick reference table	790–801	~80
F — Build-target code example	37–47	~60
Total		~850 words

Current AI-facing: 3 897 words → projected: ~3 047 words (22% reduction). The remaining bulk is WLED-MM–specific peripheral patterns (I2S audio, HUB75, mutex macros, delay/yield/IDLE), which are genuine false-positive suppressors and cannot be cut without review-quality loss.

---

cicd.instructions.md — No cuts recommended

The remaining AI-facing content (Lines 71–160) is entirely security rules: permissions least-privilege, action pinning, secret scoping, script injection. These are exactly the kind of rules that prevent false negatives in PRs. Cutting them would reduce review quality.

Minor option: Lines 109–116 ("when adding a new third-party action" checklist) could move to HUMAN_ONLY to save ~40 words, if the target is strictly 500 words.

---

copilot-instructions.md — Structural candidates

Block	Lines	Action	Words freed
Setup section	8–12	Move to HUMAN_ONLY	~30
Build and Test table	25–36	Move to HUMAN_ONLY, keep one-line summary	~90
Repository Structure tree	39–59	Move to HUMAN_ONLY	~100

Condensed AI-facing replacement for lines 39–59:

Firmware source: `wled00/` (C++). Web UI source: `wled00/data/`.
Auto-generated headers: `wled00/html_*.h` — **never edit or commit**.
Usermods: `usermods/` (`.h` files, included via `usermods_list.cpp`).
Build targets: `platformio.ini`. CI/CD: `.github/workflows/`.

Saves ~220 words total. Projected: ~538 words (still slightly above 500, but the remaining content is all actionable review guidance).

---

Summary

File	Current AI words	Proposed cut	Projected AI words
cpp.instructions.md	2 791	~800	~1 990
esp-idf.instructions.md	3 897	~850	~3 047
cicd.instructions.md	568	~40	~528
copilot-instructions.md	758	~220	~538

The two large files remain well above 500 words after this pass. The content that would need to go for the budget to be met in those files is the WLED-MM–specific peripheral sections (I2S audio, HUB75, mutex/semaphore tables, delay/yield/IDLE) — those are the highest-value false-positive suppressors in the repo and removing them would cause real review-quality loss. A pragmatic target for a second pass would be 1 500 words for cpp and 2 000 words for esp-idf, achievable by condensing the longer peripheral-section prose into bullet-only rules while moving worked examples to HUMAN_ONLY.

---

🧠 Learnings used

Learnt from: CR
Repo: MoonModules/WLED-MM PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-03T23:41:27.774Z
Learning: Applies to wled00/**/*.{cpp,h,hpp} : Document attribution of inspiration, knowledge, and sources used in code. Use `// AI:` comments for larger blocks of AI-generated code and ensure AI-generated code is well documented

---

Learnt from: softhack007
Repo: MoonModules/WLED-MM PR: 0
File: :0-0
Timestamp: 2026-04-04T14:32:02.598Z
Learning: In MoonModules/WLED-MM, clang-format is intentionally NOT enforced via CI or .clang-format config because it would cause merge conflicts when cherry-picking features from upstream WLED (which uses different formatting). Instead, "soft" formatting rules are documented in .github/cpp.instructions.md. Do not recommend adding clang-format to CI as a follow-up to missing automated enforcement — the decision is deliberate.

---

Learnt from: softhack007
Repo: MoonModules/WLED-MM PR: 0
File: :0-0
Timestamp: 2026-04-04T00:29:49.113Z
Learning: In MoonModules/WLED-MM, function-level doc comment blocks (e.g. /* ***** */ style headers) are NOT required during code reviews, especially not for previously existing functions. Do not flag missing function-level comments as review issues in this repository.

[softhack007]

@coderabbitai thanks, i'll incorporate your suggestions. I understand that reducing tokenizer output size for review rules also has a positive impact on the remaining context window that stays available as the "AI working memory", allowing a deeper understanding of the source code under review, right?

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@softhack007 — yes, your understanding is correct, and it's worth being precise about the mechanisms:

1. Shared context window budget
The context window is fixed and shared across everything in a review session: system prompt, path instructions injected per file type, the diff itself, surrounding file content fetched for cross-reference, and conversation history. Instruction tokens and code tokens compete for the same budget. Fewer instruction tokens directly means more room for code.

2. Transformer attention signal-to-noise
In a transformer architecture, attention is computed across all tokens in context. When instruction content repeats general knowledge the model already has (C++ standard semantics, common ESP-IDF API signatures, generic CI patterns), those tokens consume attention capacity without contributing new signal. Removing them improves the ratio of high-signal tokens (your actual code) to total tokens.

3. The "already internalized" effect
The key insight is that content the model learned during pre-training doesn't need to be in the context at inference time — it's already encoded in the weights. Injecting general knowledge the model already knows is pure cost with near-zero benefit. The only content worth injecting is what deviates from or extends the model's training distribution: intentional project-specific exceptions, patterns that look like bugs but aren't, WLED-MM macro semantics, etc.

4. Where the bottleneck shifts
Once instruction files are concise, the context window constraint moves to code volume. For large PRs touching many files, the reviewer may still see truncated surrounding context per file. That's where keeping per-file instructions lean matters most — it maximizes the code-to-instruction ratio in the window when reviewing each changed file.

So the 500-word-per-file-type target is a principled bound: it leaves enough headroom that a moderately large diff (say, 10 changed files, each with 200–300 lines of surrounding context) can fit comfortably alongside the instructions.

---

🧠 Learnings used

Learnt from: CR
Repo: MoonModules/WLED-MM PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-03T23:41:27.774Z
Learning: Applies to wled00/**/*.{cpp,h,hpp} : Document attribution of inspiration, knowledge, and sources used in code. Use `// AI:` comments for larger blocks of AI-generated code and ensure AI-generated code is well documented

---

Learnt from: softhack007
Repo: MoonModules/WLED-MM PR: 0
File: :0-0
Timestamp: 2026-04-04T14:32:02.598Z
Learning: In MoonModules/WLED-MM, clang-format is intentionally NOT enforced via CI or .clang-format config because it would cause merge conflicts when cherry-picking features from upstream WLED (which uses different formatting). Instead, "soft" formatting rules are documented in .github/cpp.instructions.md. Do not recommend adding clang-format to CI as a follow-up to missing automated enforcement — the decision is deliberate.

[softhack007]

@coderabbitai we cannot really achieve the "500 words" target everywhere, let's treat it as a "best case" soft objective. Current AI models have a context window of 100.000 to 400.000 embeddings, so reduction makes sense, but 500 appears to be just a "very safe guess".

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@softhack007 — agreed, and that's a well-calibrated correction.

A small precision: context windows are measured in tokens, not embeddings (embeddings are the internal vector representations of tokens). At a rough 1.3–1.5 tokens per word, your current AI-facing word counts translate to approximately:

File	AI-facing words	~Tokens
cpp.instructions.md	2,325	~3,000
esp-idf.instructions.md	3,897	~5,100
cicd.instructions.md	~528	~690
copilot-instructions.md	~538	~700

Even summed (~9,500 tokens total), that's under 10% of a 100K-token window and under 3% of a 400K window. So the 500-word target was indeed a very conservative "safe guess" — the actual headroom is much larger.

The better framing for the target going forward is:

1. Hard rule: only inject content that is WLED-MM–specific or deviates from general knowledge (the token cost of true false-positive suppressors is always worth paying).
2. Soft goal: keep each file's AI-facing section lean enough that the signal-to-noise ratio in the attention layer stays high — around 1,500–2,000 words per file type is a reasonable practical ceiling for current models.
3. Aspirational: 500 words per file if achievable without sacrificing review quality.

The progress made in this PR (moving ~1,442 words to HUMAN_ONLY in cpp.instructions.md alone) is already meaningful under this revised framing — it's not a failed attempt at 500 words but a genuine improvement in attention quality.

---

✏️ Learnings added

Learnt from: softhack007
URL: https://github.com/MoonModules/WLED-MM/pull/354

Timestamp: 2026-04-04T17:14:57.189Z
Learning: In MoonModules/WLED-MM, the "500 words per file type" target for AI-facing instruction content is a soft aspirational objective, not a hard requirement. Modern AI models have context windows of 100K–400K tokens, so the real ceiling is much higher. A practical working target is ~1,500–2,000 AI-facing words per instruction file. The primary rationale for conciseness is improving attention signal-to-noise ratio and prioritizing WLED-MM-specific content (false-positive suppressors, intentional deviations), not raw context window conservation.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

🧠 Learnings used

Learnt from: CR
Repo: MoonModules/WLED-MM PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2026-04-03T23:41:27.774Z
Learning: Applies to wled00/**/*.{cpp,h,hpp} : Document attribution of inspiration, knowledge, and sources used in code. Use `// AI:` comments for larger blocks of AI-generated code and ensure AI-generated code is well documented

---

Learnt from: softhack007
Repo: MoonModules/WLED-MM PR: 0
File: :0-0
Timestamp: 2026-04-04T14:32:02.598Z
Learning: In MoonModules/WLED-MM, clang-format is intentionally NOT enforced via CI or .clang-format config because it would cause merge conflicts when cherry-picking features from upstream WLED (which uses different formatting). Instead, "soft" formatting rules are documented in .github/cpp.instructions.md. Do not recommend adding clang-format to CI as a follow-up to missing automated enforcement — the decision is deliberate.

[softhack007]

@coderabbitai let's do a final readability check, both for the "AI facing" and for "Human full text" views.

• extract the "AI facing" part of each instructions file, and review for clarity, no content gaps, understandability for AI.
• extract the "Human facing" full instructions file, and review for clarity, readability, understandability

[softhack007]

Actually these target values would be good regardless of AI or humans writing code.
However as contributors often don't feel comfortable with English, let's first make the rule mandatory for AI only - they are language experts ;-).