240 lines
No EOL
7.8 KiB
Markdown
240 lines
No EOL
7.8 KiB
Markdown
# Decision Frameworks
|
|
|
|
**Systematic approaches for common engineering decisions.**
|
|
|
|
## When to Add Abstraction
|
|
|
|
```
|
|
Current concrete use case exists?
|
|
│
|
|
┌──────────────┴──────────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Does abstraction simplify REJECT
|
|
THIS case (not future cases)? (YAGNI)
|
|
│
|
|
┌──────────┴──────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
CONSIDER REJECT
|
|
(proceed to (add when
|
|
cost analysis) need proven)
|
|
```
|
|
|
|
### Abstraction Cost Analysis
|
|
|
|
| Cost | Question | Reject If |
|
|
|------|----------|-----------|
|
|
| Maintenance | Will someone need to understand this in 5 years? | Complexity > benefit |
|
|
| Debugging | Does indirection make tracing harder? | Yes, and no tooling helps |
|
|
| Performance | Does abstraction add measurable overhead? | Yes, and no mitigation |
|
|
| Cognitive | Does developer need to learn 2+ concepts? | Learning cost > simplicity gain |
|
|
|
|
### Valid Abstraction Reasons
|
|
|
|
- ✅ Multiple current consumers with same interface need
|
|
- ✅ Complex logic needs isolation for testability
|
|
- ✅ Performance optimization that benefits multiple paths
|
|
- ✅ Platform boundary (not just "flexibility")
|
|
|
|
### Invalid Abstraction Reasons
|
|
|
|
- ❌ "Might need it later"
|
|
- ❌ "More professional/extensible"
|
|
- ❌ "Follows design pattern X"
|
|
- ❌ "Team standard" (without concrete need)
|
|
|
|
## When to Close a Bead
|
|
|
|
```
|
|
All gates pass?
|
|
│
|
|
┌──────────┴──────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Evidence cited? Fix failures
|
|
│ then re-check
|
|
┌──────────┴──────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Notes updated? Cite evidence
|
|
│ in notes
|
|
┌─────┴─────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
CLOSE Update notes
|
|
then close
|
|
```
|
|
|
|
### Close Checklist
|
|
|
|
```
|
|
□ npm run typecheck → PASS (output cited)
|
|
□ npm run lint → PASS (output cited)
|
|
□ npm run test → PASS (output cited)
|
|
□ UI changed? → Screenshots captured, paths noted
|
|
□ Notes? → All progress documented
|
|
□ Evidence? → Commands + results cited
|
|
□ Dependencies? → Confirm blockers still resolved
|
|
```
|
|
|
|
### Close Command Template
|
|
```bash
|
|
bd update <id> --notes "Evidence:
|
|
- typecheck: PASS (0 errors)
|
|
- lint: PASS (0 warnings)
|
|
- test: PASS (N/N tests)
|
|
- [UI: screenshots at artifacts/...]"
|
|
|
|
bd close <id> --reason "Completed with full verification. [Brief summary of what was done.]"
|
|
```
|
|
|
|
## When to Fix Bug vs Patch Symptom
|
|
|
|
```
|
|
Bug found
|
|
│
|
|
▼
|
|
Why was this bug possible?
|
|
│
|
|
┌──────────────┴──────────────┐
|
|
Design flaw Isolated mistake
|
|
│ │
|
|
▼ ▼
|
|
Fix design, eliminate Patch this instance
|
|
entire bug class + add test
|
|
│ │
|
|
▼ ▼
|
|
Example: Input validation Example: Typo in
|
|
missing at boundary variable name
|
|
→ Add validation at entry → Fix typo
|
|
→ Bug class eliminated → Add spellcheck
|
|
```
|
|
|
|
### Bug Class Analysis
|
|
|
|
| Symptom | Look For | Fix At |
|
|
|---------|----------|--------|
|
|
| Null pointer | Missing validation at boundaries | Entry point validation |
|
|
| Race condition | Shared mutable state without synchronization | Data structure design |
|
|
| Off-by-one | Boundary condition pattern | Abstraction for iteration |
|
|
| Type mismatch | Weak typing at interfaces | TypeScript strict mode |
|
|
| Memory leak | Ownership unclear | RAII / ownership model |
|
|
|
|
### Linus's Approach
|
|
|
|
1. **Trace to root cause** - Not just "where it crashed"
|
|
2. **Ask "why was this possible?"** - What enabled this bug class?
|
|
3. **Fix design if needed** - Better to eliminate bug class than patch instances
|
|
4. **Add regression test** - Ensure class can't return
|
|
|
|
## When to Refactor
|
|
|
|
```
|
|
Pain point exists?
|
|
│
|
|
┌──────────┴──────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Pain quantified? Don't refactor
|
|
│ (premature)
|
|
┌──────────┴──────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Benefit > cost? Quantify first
|
|
│ (measure pain)
|
|
┌─┴─┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Refactor Don't refactor
|
|
now (track as bead)
|
|
```
|
|
|
|
### Refactor Quantification
|
|
|
|
| Pain | Measurement | Threshold |
|
|
|------|-------------|-----------|
|
|
| Slow | Profile, ms | >100ms hot path |
|
|
| Confusing | PR comments, questions | >3 questions/month |
|
|
| Bug-prone | Bug count in area | >2 bugs/quarter |
|
|
| Slow to change | Time to add feature | >2x expected |
|
|
|
|
### Refactor Rules
|
|
|
|
- ✅ Have test coverage first
|
|
- ✅ Measure before and after
|
|
- ✅ One vertical slice at a time
|
|
- ❌ Don't refactor "while here" without tracking
|
|
- ❌ Don't refactor for style without measurable benefit
|
|
|
|
## When to Create Bead
|
|
|
|
```
|
|
Work identified
|
|
│
|
|
▼
|
|
Will it take >30 min?
|
|
│
|
|
┌──────────┴──────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Has dependencies? Just do it
|
|
│ (no bead needed)
|
|
┌──────┴──────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Create bead Create bead
|
|
with deps (simple task)
|
|
```
|
|
|
|
### Bead Worth Creating If
|
|
|
|
- Spans sessions / needs compaction survival
|
|
- Has dependencies / blockers
|
|
- Complex acceptance criteria
|
|
- Needs collaboration
|
|
- Risk of context loss
|
|
|
|
### No Bead Needed If
|
|
|
|
- <30 minutes single session
|
|
- No dependencies
|
|
- Clear immediate action
|
|
- Will complete in this session
|
|
|
|
## When to Parallelize
|
|
|
|
```
|
|
Multiple independent tasks?
|
|
│
|
|
┌──────────┴──────────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Shared state needed? Execute sequentially
|
|
│
|
|
┌──────┴──────┐
|
|
YES NO
|
|
│ │
|
|
▼ ▼
|
|
Sequential PARALLELIZE
|
|
(avoid races) via subagents
|
|
```
|
|
|
|
### Parallelization Rules
|
|
|
|
- ✅ No shared state between tasks
|
|
- ✅ No read-after-write dependencies
|
|
- ✅ Each task owns distinct files
|
|
- ❌ Don't parallelize if tasks modify same files
|
|
- ❌ Don't parallelize if order matters for correctness |