Seth-Workflow-April-2026/rules/05-reasoning-patterns.md

# Reasoning & Quality Patterns

Structured thinking patterns that improve output quality. Apply them automatically based on context.

## Clarification Before Assumption

**When requirements are vague, ASK rather than assume.**

Before starting work on ambiguous requests:
1. Identify what's unclear (scope, approach, constraints)
2. List 2-3 specific clarifying questions
3. Wait for answers before proceeding

**Trigger phrases requiring clarification:**
- "Make it better" -- Better how? Performance? Readability? UX?
- "Fix the bug" -- Which bug? What's the expected behavior?
- "Add a feature" -- What exactly should it do? Who uses it?
- "Improve this" -- What metric defines improvement?

**Format:**
> Before I proceed, I need to clarify:
> 1. [Specific question about scope/approach]
> 2. [Specific question about constraints/preferences]

## Brainstorming Before Building

**For non-trivial features, brainstorm approaches first.**

When facing implementation decisions:
1. Generate 2-3 distinct approaches
2. List pros/cons for each
3. Recommend one with reasoning
4. Get user confirmation before coding

**Apply when:**
- Multiple valid architectures exist
- Trade-offs between simplicity and flexibility
- New feature with unclear best practice
- Performance vs maintainability decisions

## Reflection Before Completion

**Review work before declaring done.**

After completing significant work, pause and verify:

```
Pre-Completion Checklist:
- [ ] Does this actually solve the stated problem?
- [ ] Did I miss any edge cases mentioned in requirements?
- [ ] Are there obvious improvements I should mention?
- [ ] Would I be comfortable if someone else reviewed this?
```

**Self-review questions:**
1. "If I were the user, would this answer satisfy me?"
2. "What's the weakest part of this solution?"
3. "What would a senior engineer critique?"

## Five Whys for Debugging

**Trace problems to root cause, not symptoms.**

When debugging:
1. **Why** did this fail? -- [immediate cause]
2. **Why** did that happen? -- [deeper cause]
3. **Why** was that possible? -- [systemic cause]
4. **Why** wasn't this caught? -- [process gap]
5. **Why** does this gap exist? -- [root cause]

Stop when you reach something actionable. Fix the root cause, not just the symptom.

## First Principles for Complex Problems

**Break down complex problems to fundamentals.**

When stuck or facing novel challenges:

1. **What do we know for certain?** (facts, constraints)
2. **What are we assuming?** (challenge each assumption)
3. **What's the simplest version?** (minimum viable solution)
4. **What would we do differently with no legacy?** (ideal state)
5. **What's the path from here to there?** (incremental steps)

## Research Before Recommending

**Don't guess at library APIs or best practices.**

When recommending technologies or approaches:
1. Check if you confidently know the answer (common patterns, stable APIs)
2. For simple lookups, fetch official documentation (lightweight)
3. For complex queries, use heavier documentation tools (sparingly)
4. Cite sources for recommendations

### Documentation Lookup Tiers (Token-Conscious)

**Tier 1 - Use existing knowledge** (0 extra tokens):
- Standard library functions
- Well-known frameworks with stable APIs
- Common patterns you're confident about

**Tier 2 - Lightweight fetch** (~500-2k tokens):
- Simple API questions, single function lookups
- Fetching a specific documentation page

**Tier 2.5 - LLM-optimized docs** (~1-5k tokens):
- Check `<docs-site>/llms.txt` (many sites expose this)
- More complete than single-page fetch, cheaper than full docs

**Tier 3 - Heavy documentation tools** (~5-20k tokens per query):
- Complex multi-part queries needing code examples
- Unfamiliar or rapidly-changing libraries
- When lighter tiers failed to answer

**Never say:** "I think the API works like..."
**Instead:** "According to the documentation..." or "Let me check the current docs."

## Research Quality Rules

1. **Every factual claim needs a source citation**
   - Link to documentation, commit, or authoritative source
   - If citing from memory, mark as "[from knowledge, not verified]"

2. **Flag single-source claims**
   - If only one source says it, mark as "[unverified]"
   - Cross-reference critical claims (security, performance, compatibility)

3. **Separate fact from inference**
   - Fact: "The API rate limit is 100/min" (documented)
   - Inference: "This suggests we need caching" (my conclusion)
   - Always label which is which

4. **Cross-reference critical claims**
   - Security recommendations: verify in multiple sources
   - Performance claims: benchmark or cite benchmarks
   - Compatibility claims: test or cite test results

## Adopt/Extend/Compose/Build Matrix

**Before implementing custom solutions, evaluate existing options.**

| Option | When | Example |
|--------|------|---------|
| **Adopt** | Existing solution fits 100% | Use library directly |
| **Extend** | Fits 80%, need customization | Extend base class, wrap API |
| **Compose** | Multiple tools solve parts | Combine libraries for full solution |
| **Build** | Nothing fits, unique requirement | Custom implementation |

**Default to Adopt.** Building is the last resort -- every line of custom code is a maintenance burden. The threshold for "Build" should be high: no existing tool covers even 50% of the need, AND the requirement is genuinely unique.