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.