Skip to content

Commit 21565a5

Browse files
wallstopwallstop
committed
PR feedback
1 parent 0940fcf commit 21565a5

File tree

6 files changed

+242
-36
lines changed

6 files changed

+242
-36
lines changed

‎.llm/context.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ Invoke these skills for specific tasks.
8383
**Regenerate with**: `pwsh -NoProfile -File scripts/generate-skills-index.ps1`
8484

8585
<!-- BEGIN GENERATED SKILLS INDEX -->
86-
<!-- Generated: 2026-01-21 11:38:27 UTC -->
86+
<!-- Generated: 2026-01-24 15:34:43 UTC -->
8787
<!-- Command: pwsh -NoProfile -File scripts/generate-skills-index.ps1 -->
8888

8989
### Core Skills (Always Consider)
@@ -101,6 +101,7 @@ Invoke these skills for specific tasks.
101101
| [create-unity-meta](./skills/create-unity-meta.md) | After creating ANY new file or folder |
102102
| [defensive-editor-programming](./skills/defensive-editor-programming.md) | Editor code - handle Unity Editor edge cases |
103103
| [defensive-programming](./skills/defensive-programming.md) | ALL code - never throw, handle gracefully |
104+
| [documentation-consistency](./skills/documentation-consistency.md) | When writing or reviewing documentation |
104105
| [editor-caching-patterns](./skills/editor-caching-patterns.md) | Caching strategies for Editor code |
105106
| [formatting](./skills/formatting.md) | After ANY file change (CSharpier/Prettier) |
106107
| [git-hook-patterns](./skills/git-hook-patterns.md) | Pre-commit hook safety and configuration |

‎.llm/skills/documentation-consistency.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
# Skill: Documentation Consistency
2+
3+
<!-- trigger: docs consistency, cross-file consistency, performance claims, time estimates | When writing or reviewing documentation | Core -->
4+
5+
**Trigger**: When writing or reviewing documentation across multiple files (root README, docs readme, docs index, etc.)
6+
7+
---
8+
9+
## When to Use
10+
11+
This skill applies when creating or modifying documentation that appears in multiple locations or makes claims that must be consistent across the codebase.
12+
13+
---
14+
15+
## When NOT to Use
16+
17+
This skill is NOT needed for:
18+
19+
- **Single-file documentation changes** — No cross-file consistency to maintain
20+
- **Internal code comments** — Not user-facing, no consistency requirement
21+
- **Test files or examples** — Isolated documentation, doesn't need to match other files
22+
- **CHANGELOG entries** — Already have their own format rules (see [update-documentation](./update-documentation.md))
23+
- **XML documentation comments** — Per-member docs, not cross-file claims
24+
25+
---
26+
27+
## Key Principles
28+
29+
### 1. Performance Claims Must Be Consistent
30+
31+
Performance numbers MUST match across all documentation files. If a benchmark shows a range, use the same range everywhere.
32+
33+
| ❌ Inconsistent | ✅ Consistent |
34+
| -------------------------------------------------------- | ---------------------------------------------------------- |
35+
| README says "100x faster", docs/readme says "12x faster" | All files say "10-100x faster (varies by operation)" |
36+
| One file says "up to 15x", another says "10-15x" | All files use the same phrasing: "10-15x faster" |
37+
| Vague claim without context | Specific claim with context: "~12x for method invocations" |
38+
39+
**Best Practice**: When performance varies by scenario, document the range AND explain what affects it:
40+
41+
```markdown
42+
<!-- ✅ GOOD: Clear, consistent, explains variance -->
43+
44+
Cached delegates are 10-100x faster than raw `System.Reflection`
45+
(method invocations ~12x; boxed scenarios up to 100x)
46+
47+
<!-- ❌ BAD: Inconsistent claims in different files -->
48+
49+
File A: "100x faster than System.Reflection"
50+
File B: "up to 12x faster than System.Reflection"
51+
```
52+
53+
### 2. Time Estimates Use Tilde (~) Prefix
54+
55+
All time estimates should use the tilde (~) prefix to indicate approximation.
56+
57+
| ❌ Without tilde | ✅ With tilde |
58+
| ---------------- | ------------- |
59+
| 2 minutes | ~2 minutes |
60+
| 5 minutes | ~5 minutes |
61+
| 10 minutes | ~10 minutes |
62+
| 1 minute | ~1 minute |
63+
64+
**Example table**:
65+
66+
```markdown
67+
| Task | Time to Value |
68+
| ----------------------- | ------------- |
69+
| Inspector Tooling setup | ~2 minutes |
70+
| Component wiring | ~2 minutes |
71+
| Effects system | ~5 minutes |
72+
```
73+
74+
### 3. Avoid Run-On Sentences
75+
76+
Don't combine multiple distinct claims in a single sentence. Break them into clear, scannable points.
77+
78+
```markdown
79+
<!-- ❌ BAD: Run-on sentence combining multiple claims -->
80+
81+
Random generation is 10-15x faster than Unity.Random (see benchmarks),
82+
spatial queries use O(log n) algorithms for efficient large dataset handling,
83+
and declarative inspector attributes can reduce custom editor code.
84+
85+
<!-- ✅ GOOD: Separated into clear points -->
86+
87+
Key performance highlights:
88+
89+
- 10-15x faster random generation than Unity.Random (see benchmarks)
90+
- O(log n) spatial queries for efficient large dataset handling
91+
- Declarative inspector attributes to reduce custom editor code
92+
```
93+
94+
### 4. Eliminate Redundancy
95+
96+
Don't repeat the same concept with different wording in the same section.
97+
98+
```markdown
99+
<!-- ❌ BAD: Redundant statements -->
100+
101+
### Schema Evolution
102+
103+
Schema evolution support for backward-compatible serialization.
104+
Forward and backward compatible serialization.
105+
106+
<!-- ✅ GOOD: Single clear statement -->
107+
108+
### Schema Evolution
109+
110+
Forward and backward compatible serialization — add new fields
111+
without breaking existing saves.
112+
```
113+
114+
### 5. Use Clear, Unambiguous Phrasing
115+
116+
Avoid phrasing that could be misread or misunderstood.
117+
118+
```markdown
119+
<!-- ❌ BAD: Awkward, could be misread -->
120+
121+
Benchmarks show 10-15x faster random generation than Unity.Random
122+
123+
<!-- ✅ GOOD: Clear comparison structure -->
124+
125+
Benchmarks demonstrate 10-15x faster random generation compared to Unity.Random
126+
```
127+
128+
### 6. Dependency Claims Must Be Accurate
129+
130+
Dependency descriptions must accurately reflect the package structure.
131+
132+
| Scenario | Correct Description |
133+
| ---------------------------------- | ------------------------------------------------ |
134+
| Dependency is bundled with package | "Zero external dependencies — [name] is bundled" |
135+
| Dependency must be installed | "Requires [name] for [feature]" |
136+
| Optional dependency | "Optional: [name] for [feature]" |
137+
138+
```markdown
139+
<!-- ✅ GOOD: Accurate for bundled dependency -->
140+
141+
- ✅ **Zero external dependencies** — protobuf-net is bundled for binary serialization
142+
143+
<!-- ❌ BAD: Confusing/contradictory -->
144+
145+
- ✅ **Minimal external dependencies** - depends on protobuf-net for binary serialization
146+
```
147+
148+
---
149+
150+
## Cross-File Consistency Checklist
151+
152+
When updating documentation, verify these items are consistent across ALL documentation files:
153+
154+
### Performance Claims
155+
156+
- [ ] Random generation speed (e.g., "10-15x faster than Unity.Random")
157+
- [ ] Reflection speedup (e.g., "10-100x faster, varies by operation")
158+
- [ ] Spatial query complexity (e.g., "O(log n)")
159+
- [ ] Test count (e.g., "8,000+ tests")
160+
161+
### Feature Descriptions
162+
163+
- [ ] Dependency status (zero/bundled/external)
164+
- [ ] Platform support claims (IL2CPP, WebGL, etc.)
165+
- [ ] Compatibility statements (Unity versions)
166+
167+
### Formatting
168+
169+
- [ ] Time estimates use tilde (~) prefix
170+
- [ ] Consistent use of bold/emphasis
171+
- [ ] Consistent bullet point style
172+
173+
---
174+
175+
## Files to Cross-Reference
176+
177+
When making documentation changes, check these files for consistency:
178+
179+
| File | Purpose |
180+
| ----------------------------------------------------------------------- | --------------------------- |
181+
| [README](../../README.md) | Root project readme |
182+
| [docs/readme](../../docs/readme.md) | Detailed documentation |
183+
| [docs/index](../../docs/index.md) | Documentation site homepage |
184+
| [docs/overview/getting-started](../../docs/overview/getting-started.md) | Onboarding guide |
185+
| [llms.txt](../../llms.txt) | LLM-friendly summary |
186+
187+
---
188+
189+
## Common Mistakes
190+
191+
| Mistake | Impact | Fix |
192+
| -------------------------------------- | ------------------------------------ | ------------------------------------------- |
193+
| Different performance numbers in files | Undermines credibility | Use exact same numbers everywhere |
194+
| Missing tilde on time estimates | Implies false precision | Add ~ prefix to all estimates |
195+
| Run-on sentences with multiple claims | Hard to scan, reduces comprehension | Break into bullet points or short sentences |
196+
| Redundant statements | Wastes reader time, looks unpolished | Consolidate to single clear statement |
197+
| Contradictory dependency claims | Confuses users about requirements | Clarify bundled vs external status |
198+
199+
---
200+
201+
## Related Skills
202+
203+
- [update-documentation](./update-documentation.md) — When and how to update docs
204+
- [markdown-reference](./markdown-reference.md) — Markdown formatting rules
205+
- [validate-before-commit](./validate-before-commit.md) — Pre-commit validation

‎README.md‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@
3535

3636
**Reduce time spent on boilerplate and focus more on features.**
3737

38-
Unity Helpers provides production-ready utilities designed to improve development speed. Random generation is 10-15x faster than Unity.Random (see benchmarks), spatial queries use O(log n) algorithms for efficient large dataset handling, and declarative inspector attributes can reduce custom editor code.
38+
Unity Helpers provides production-ready utilities designed to improve development speed. Key performance highlights: 10-15x faster random generation than Unity.Random (see benchmarks), O(log n) spatial queries, and declarative inspector attributes to reduce custom editor code.
3939

4040
---
4141

@@ -92,15 +92,15 @@ Unity Helpers provides production-ready utilities designed to improve developmen
9292

9393
| Your Problem | Your Solution | Time to Value |
9494
| ------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------- |
95-
| 🎨 Writing custom editors | [**Inspector Tooling**](#1--professional-inspector-tooling) - Inspector tooling for common use cases | 2 minutes |
96-
| 🐌 Writing `GetComponent` everywhere | [**Relational Components**](#2--auto-wire-components) - Auto-wire with attributes | 2 minutes |
97-
| 🎮 Need buffs/debuffs system | [**Effects System**](#3--data-driven-effects) - Designer-friendly ScriptableObjects | 5 minutes |
98-
| 🔍 Slow spatial searches | [**Spatial Trees**](#spatial-trees) - O(log n) queries | 5 minutes |
99-
| 🎲 Random is too slow/limited | [**PRNG.Instance**](#random-number-generators) - 10-15x faster, extensive API | 1 minute |
100-
| 💾 Need save/load system | [**Serialization**](#4--unity-aware-serialization) - Unity types just work | 10 minutes |
101-
| 🛠️ Manual sprite workflows | [**Editor Tools**](#editor-tools) - 20+ automation tools | 3 minutes |
95+
| 🎨 Writing custom editors | [**Inspector Tooling**](#1--professional-inspector-tooling) - Inspector tooling for common use cases | ~2 minutes |
96+
| 🐌 Writing `GetComponent` everywhere | [**Relational Components**](#2--auto-wire-components) - Auto-wire with attributes | ~2 minutes |
97+
| 🎮 Need buffs/debuffs system | [**Effects System**](#3--data-driven-effects) - Designer-friendly ScriptableObjects | ~5 minutes |
98+
| 🔍 Slow spatial searches | [**Spatial Trees**](#spatial-trees) - O(log n) queries | ~5 minutes |
99+
| 🎲 Random is too slow/limited | [**PRNG.Instance**](#random-number-generators) - 10-15x faster, extensive API | ~1 minute |
100+
| 💾 Need save/load system | [**Serialization**](#4--unity-aware-serialization) - Unity types just work | ~10 minutes |
101+
| 🛠️ Manual sprite workflows | [**Editor Tools**](#editor-tools) - 20+ automation tools | ~3 minutes |
102102

103-
**Not sure where to start?** → [Getting Started Guide](./docs/overview/getting-started.md) walks through the top 3 features in 5 minutes.
103+
**Not sure where to start?** → [Getting Started Guide](./docs/overview/getting-started.md) walks through the top 3 features in ~5 minutes.
104104

105105
---
106106

@@ -285,7 +285,7 @@ void ProcessEnemies(QuadTree2D<Enemy> enemyTree) {
285285
**Common workflows:**
286286

287287
- **Sprite Cropper**: Add or remove transparent pixels from 500 sprites → 1 click (was: 30 minutes in Photoshop)
288-
- **Animation Creator**: Bulk-create clips from naming patterns (`walk_0001.png`) → 1 minute (was: 20 minutes)
288+
- **Animation Creator**: Bulk-create clips from naming patterns (`walk_0001.png`) → ~1 minute (was: ~20 minutes)
289289
- **Prefab Checker**: Validate 200 prefabs for missing references → 1 click (was: manual QA)
290290
- **Atlas Generator**: Create sprite atlases from regex/labels → automated (was: manual setup)
291291

@@ -362,14 +362,14 @@ string apiKey = "user_name".ToPascalCase(); // "UserName"
362362

363363
These powerful utilities solve specific problems that waste hours if you implement them yourself:
364364

365-
| Feature | What It Does | Benefit |
366-
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------- |
367-
| **[Predictive Targeting](./docs/features/utilities/helper-utilities.md#predictive-aiming)** | Perfect ballistics for turrets/missiles in one call | Simplifies implementation |
368-
| **[Coroutine Jitter](./docs/features/utilities/math-and-extensions.md#unity-extensions)** | Prevents 100 enemies polling on same frame | Reduces frame spikes |
369-
| **[IL-Emitted Reflection](./docs/features/utilities/reflection-helpers.md)** | 100x faster than System.Reflection, IL2CPP safe | Improves serialization performance |
370-
| **[SmartDestroy()](./docs/features/utilities/helper-utilities.md#smart-destruction)** | Editor/runtime safe destruction (no scene corruption) | Works across editor/runtime |
371-
| **[Convex/Concave Hulls](./docs/features/spatial/hulls.md)** | Generate territory borders from point clouds | Avoids manual hull calculation |
372-
| **[Logging Extensions](./docs/features/logging/logging-extensions.md)** | Rich tags, thread-aware logs, per-object toggles | Improves debugging |
365+
| Feature | What It Does | Benefit |
366+
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------- |
367+
| **[Predictive Targeting](./docs/features/utilities/helper-utilities.md#predictive-aiming)** | Perfect ballistics for turrets/missiles in one call | Simplifies implementation |
368+
| **[Coroutine Jitter](./docs/features/utilities/math-and-extensions.md#unity-extensions)** | Prevents 100 enemies polling on same frame | Reduces frame spikes |
369+
| **[IL-Emitted Reflection](./docs/features/utilities/reflection-helpers.md)** | 10-100x faster than System.Reflection (varies by operation), IL2CPP safe | Improves serialization performance |
370+
| **[SmartDestroy()](./docs/features/utilities/helper-utilities.md#smart-destruction)** | Editor/runtime safe destruction (no scene corruption) | Works across editor/runtime |
371+
| **[Convex/Concave Hulls](./docs/features/spatial/hulls.md)** | Generate territory borders from point clouds | Avoids manual hull calculation |
372+
| **[Logging Extensions](./docs/features/logging/logging-extensions.md)** | Rich tags, thread-aware logs, per-object toggles | Improves debugging |
373373

374374
---
375375

@@ -381,7 +381,7 @@ Common Unity development patterns like GetComponent calls, spatial queries, and
381381

382382
- ✅ **Production-tested** in shipped commercial games
383383
- ✅ **8,000+ automated tests** catch edge cases before you hit them
384-
- ✅ **Zero dependencies** - drop it in any project
384+
- ✅ **Zero external dependencies** — protobuf-net is bundled for binary serialization
385385
- ✅ **IL2CPP/WebGL ready** with optimized SINGLE_THREADED paths
386386
- ✅ **MIT Licensed** - use freely in commercial projects
387387

@@ -1267,7 +1267,7 @@ Unity Helpers is built with performance as a top priority:
12671267

12681268
**Reflection:**
12691269

1270-
- Cached delegates are 10-100x faster than raw `System.Reflection` (boxed scenarios improve the most)
1270+
- Cached delegates are 10-100x faster than raw `System.Reflection` (method invocations ~12x; boxed scenarios up to 100x)
12711271
- Safe for IL2CPP and AOT platforms; capability overrides (`ReflectionHelpers.OverrideReflectionCapabilities`) let tests force expression/IL fallbacks
12721272
- Run the benchmarks via **ReflectionPerformanceTests.Benchmark** (EditMode Test Runner) and commit the updated markdown section
12731273
- [📘 Reflection Helpers Guide](./docs/features/utilities/reflection-helpers.md) and [📊 Benchmarks](./docs/performance/reflection-performance.md)

‎docs/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ description: Production-ready Unity utilities - 10-15x faster PRNGs, O(log n) sp
1717

1818
**Utilities tested in commercial releases**
1919

20-
Unity Helpers reduces repetitive work with utilities tested in commercial releases. Benchmarks show 10-15x faster random generation than Unity.Random and significant speedups for common reflection operations. From auto-wiring components to fast spatial queries, this toolkit provides common utilities for Unity development.
20+
Unity Helpers reduces repetitive work with utilities tested in commercial releases. Benchmarks demonstrate 10-15x faster random generation compared to Unity.Random and significant speedups for common reflection operations. From auto-wiring components to fast spatial queries, this toolkit provides common utilities for Unity development.
2121

2222
---
2323

@@ -260,7 +260,7 @@ Compatible with IL2CPP and WebGL. Includes optimizations for AOT compilation.
260260

261261
### Schema Evolution
262262

263-
Schema evolution support for backward-compatible serialization. Forward and backward compatible serialization.
263+
Forward and backward compatible serialization — add new fields without breaking existing saves.
264264

265265
</div>
266266

0 commit comments

Comments
 (0)