que01
e08af11b7d
Three of this task's defects were cross-layer wiring rather than logic, so they belong in the spec where the next session will read them, not only in the task's research notes. Frontend: a new client spec covering layer ownership (baseline is never written, preview hides rather than overwrites), why a handle carries only its id, why a handle's position must derive from the clamped value, the ban on computing inside a setState updater, and why per-pointermove React state is the wrong owner of per-frame feedback. Backend: the left/right convention now states the three places that must agree and why a sign convention can be wrong on both sides of the wire at once; a table of the four profile fields the geometry stage actually reads, so nobody builds UI for interval-scoped editing again before the compiler honours it; and the save-is-not-applying contract, including that compileFresh must be installed by every path that sets session.area. Also records that an identity test cannot catch an ignored editsFile, and that a regression test is only trustworthy once it has been seen to fail. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# Thinking Guides
|
|
|
|
> **Purpose**: Expand your thinking to catch things you might not have considered.
|
|
|
|
---
|
|
|
|
## Why Thinking Guides?
|
|
|
|
**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
|
|
|
|
- Didn't think about what happens at layer boundaries → cross-layer bugs
|
|
- Didn't think about code patterns repeating → duplicated code everywhere
|
|
- Didn't think about edge cases → runtime errors
|
|
- Didn't think about future maintainers → unreadable code
|
|
|
|
These guides help you **ask the right questions before coding**.
|
|
|
|
---
|
|
|
|
## Available Guides
|
|
|
|
| Guide | Purpose | When to Use |
|
|
|-------|---------|-------------|
|
|
| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
|
|
| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
|
|
|
|
---
|
|
|
|
## Quick Reference: Thinking Triggers
|
|
|
|
### When to Think About Cross-Layer Issues
|
|
|
|
- [ ] Feature touches 3+ layers (API, Service, Component, Database)
|
|
- [ ] Data format changes between layers
|
|
- [ ] Multiple consumers need the same data
|
|
- [ ] You're not sure where to put some logic
|
|
- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
|
|
- [ ] UI / command code starts casting raw payload fields directly
|
|
|
|
→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
|
|
|
|
### When to Think About Code Reuse
|
|
|
|
- [ ] You're writing similar code to something that exists
|
|
- [ ] You see the same pattern repeated 3+ times
|
|
- [ ] You're adding a new field to multiple places
|
|
- [ ] **You're modifying any constant or config**
|
|
- [ ] **You're creating a new utility/helper function** ← Search first!
|
|
- [ ] Two files read the same untyped payload field with local casts
|
|
- [ ] Multiple branches update the same derived state from `kind` / `action`
|
|
|
|
→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
|
|
|
|
### When Verifying AI Cross-Review Results
|
|
|
|
- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
|
|
- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
|
|
- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
|
|
- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
|
|
|
|
**Common AI reviewer false-positive patterns**:
|
|
1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
|
|
2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
|
|
3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
|
|
|
|
**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
|
|
|
|
---
|
|
|
|
## Pre-Modification Rule (CRITICAL)
|
|
|
|
> **Before changing ANY value, ALWAYS search first!**
|
|
|
|
```bash
|
|
# Search for the value you're about to change
|
|
grep -r "value_to_change" .
|
|
```
|
|
|
|
This single habit prevents most "forgot to update X" bugs.
|
|
|
|
---
|
|
|
|
## How to Use This Directory
|
|
|
|
1. **Before coding**: Skim the relevant thinking guide
|
|
2. **During coding**: If something feels repetitive or complex, check the guides
|
|
3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
Found a new "didn't think of that" moment? Add it to the relevant guide.
|
|
|
|
---
|
|
|
|
**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
|