init: scaffold Seth-Workflow-April-2026

User-agnostic, shareable AI-assisted development workflow distilled from 26+ real projects. Includes 9 composable rules, 4 project templates, pre-push secret scanning hook, 3 methodology guides, and customization docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 15:55:58 -04:00
commit 9ff8e915b8
22 changed files with 1917 additions and 0 deletions
@@ -0,0 +1,149 @@
+# 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.