Initial commit

references/common-patterns.md

@@ -0,0 +1,300 @@
+# Common Patterns and Pitfalls
+
+This reference catalogs frequently encountered patterns in documents and common analytical pitfalls to avoid.
+
+## Document Patterns
+
+### Persuasive Techniques to Recognize
+
+**Authority Appeals:**
+- Pattern: "As [expert/company] does..."
+- Watch for: Cherry-picked examples, ignoring context differences
+- Question: Does their context match yours?
+
+**Bandwagon Effects:**
+- Pattern: "Everyone is moving to..."
+- Watch for: Exaggeration of adoption, ignoring failures
+- Question: What's the actual evidence? Who's not adopting and why?
+
+**Complexity Hiding:**
+- Pattern: "Simply do X" or "Just Y"
+- Watch for: Downplaying difficulty, ignoring prerequisites
+- Question: What's the real complexity? What could go wrong?
+
+**False Dichotomies:**
+- Pattern: "Either X or Y"
+- Watch for: Missing middle ground, other alternatives
+- Question: What other options exist?
+
+**Survivorship Bias:**
+- Pattern: Success stories without failure context
+- Watch for: Missing information about what didn't work
+- Question: How many tried and failed? What's the selection bias?
+
+### Structural Patterns
+
+**Problem-Solution-Benefit:**
+- Common in tech blogs and marketing
+- Watch for: Problem exaggeration, solution oversimplification
+- Verify: Is problem real? Is solution complete?
+
+**Before-After:**
+- Common in retrospectives and case studies
+- Watch for: Overfitting to specific context, ignoring other factors
+- Verify: What else changed? Is causation clear?
+
+**Theory-Evidence-Conclusion:**
+- Common in academic and analytical writing
+- Watch for: Evidence cherry-picking, logical leaps
+- Verify: Is evidence representative? Does conclusion follow?
+
+## Analytical Pitfalls
+
+### Confirmation Bias
+
+**Pattern:** Looking for information that confirms existing beliefs
+
+**How it manifests:**
+- Focusing on supporting evidence while ignoring contradictions
+- Interpreting ambiguous information favorably
+- Remembering hits and forgetting misses
+
+**Counter-strategy:**
+- Actively seek disconfirming evidence
+- Steelman opposing views
+- Ask "What would prove me wrong?"
+
+### Dunning-Kruger Effect
+
+**Pattern:** Overestimating understanding of complex topics
+
+**How it manifests:**
+- Thinking you understand after superficial reading
+- Missing subtle complexities
+- Overconfidence in applying concepts
+
+**Counter-strategy:**
+- Try to teach it to someone
+- Attempt implementation
+- Identify what you don't know
+
+### Availability Heuristic
+
+**Pattern:** Overweighting easily recalled examples
+
+**How it manifests:**
+- Recent experiences seem more relevant
+- Vivid examples dominate thinking
+- Common cases seem universal
+
+**Counter-strategy:**
+- Seek statistical baselines
+- Look for quiet counterexamples
+- Question representativeness
+
+### Hindsight Bias
+
+**Pattern:** "I knew it all along" after seeing outcomes
+
+**How it manifests in retrospectives:**
+- Outcomes seem more inevitable than they were
+- Overlooking genuine uncertainty at decision time
+- Undervaluing decisions that happened to work out
+
+**Counter-strategy:**
+- What was known at decision time?
+- What uncertainties existed?
+- What could have gone differently?
+
+### Context Collapse
+
+**Pattern:** Ignoring contextual constraints and factors
+
+**How it manifests:**
+- "Why don't they just..."
+- Assuming your context matches author's
+- Missing organizational/cultural factors
+
+**Counter-strategy:**
+- Map explicit context: stack, scale, team, timeline
+- Identify implicit context: expertise, resources, constraints
+- Consider counter-factuals: what if context differed?
+
+## Content-Specific Patterns
+
+### Tech Blog Patterns
+
+**"Magic Solution" Pattern:**
+- Presents one approach as universal answer
+- Reality: Every approach has trade-offs
+- Ask: When does this NOT work?
+
+**"Works on My Machine" Pattern:**
+- Success in specific environment
+- Reality: May not generalize
+- Ask: What's special about this environment?
+
+**"Premature Optimization" Pattern:**
+- Complex solution to simple problem
+- Reality: Simpler approaches often sufficient
+- Ask: What's the simplest approach that works?
+
+### Retrospective Patterns
+
+**"Hero's Journey" Pattern:**
+- Obstacles → Struggles → Triumph
+- Reality: Often luck, timing, or missing context
+- Ask: What role did circumstances play?
+
+**"Lessons Learned" Pattern:**
+- Lists of takeaways
+- Reality: May be overgeneralized
+- Ask: What contexts do these apply to?
+
+**"If I Knew Then" Pattern:**
+- Advice from hindsight
+- Reality: Knowledge wasn't available then
+- Ask: What was actually knowable?
+
+### Technical Documentation Patterns
+
+**"Happy Path Only" Pattern:**
+- Documents ideal use cases
+- Reality: Edge cases and errors matter
+- Ask: What can go wrong?
+
+**"Assumes Expert" Pattern:**
+- Missing prerequisite knowledge
+- Reality: Users have varying backgrounds
+- Ask: What's assumed as known?
+
+**"Version Lag" Pattern:**
+- Documentation trails implementation
+- Reality: Features changed, docs didn't
+- Ask: Is this current? What changed?
+
+### Academic Paper Patterns
+
+**"Novel Technique" Pattern:**
+- Emphasizes novelty
+- Reality: May be incremental or narrow
+- Ask: What's genuinely new vs repackaged?
+
+**"Statistical Significance" Pattern:**
+- p < 0.05 therefore important
+- Reality: Statistical ≠ practical significance
+- Ask: What's the effect size? Does it matter?
+
+**"Future Work" Pattern:**
+- Lists limitations as future work
+- Reality: May indicate fundamental flaws
+- Ask: Are these minor gaps or major issues?
+
+## Red Flags
+
+Watch for these warning signs:
+
+**Credibility Issues:**
+- Anonymous or unclear authorship
+- No sources for bold claims
+- Credentials don't match domain
+- Conflicts of interest not disclosed
+
+**Methodological Issues:**
+- Unreproducible steps
+- Missing crucial details
+- Cherry-picked results
+- No discussion of alternatives
+
+**Logical Issues:**
+- Circular reasoning
+- False dichotomies
+- Correlation → causation
+- Generalizing from single case
+
+**Practical Issues:**
+- "Just trust me" explanations
+- Missing costs or trade-offs
+- Ignoring deployment challenges
+- Unrealistic assumptions
+
+## Strengthening Your Analysis
+
+### Build Reference Classes
+
+**Instead of single data point:**
+- How many have tried this?
+- What's the success rate?
+- What patterns exist across cases?
+
+### Seek Disconfirmation
+
+**Actively look for:**
+- Opposing viewpoints
+- Failure cases
+- Limitations and boundaries
+- Alternative explanations
+
+### Map Uncertainty
+
+**Identify what's:**
+- Known and verified
+- Assumed but reasonable
+- Speculative or uncertain
+- Unknown or missing
+
+### Consider Stakeholders
+
+**Ask who:**
+- Benefits from this framing?
+- Would disagree and why?
+- Isn't represented here?
+- Has conflicting incentives?
+
+## Meta-Patterns
+
+### Evolution of Ideas
+
+**Trace idea lineage:**
+- Where did this come from?
+- How has it evolved?
+- What criticisms emerged?
+- What's the current consensus?
+
+### Domain Transfer
+
+**When ideas cross domains:**
+- What gets lost in translation?
+- What analogies are imperfect?
+- What needs adaptation?
+
+### Zeitgeist Effects
+
+**Recognize current trends:**
+- What's fashionable now?
+- What pressures shape discourse?
+- What's being over/under-valued?
+- What will look different in 5 years?
+
+## Practical Guidelines
+
+**Before accepting claims:**
+1. Identify the evidence provided
+2. Consider alternative explanations
+3. Check for context dependency
+4. Assess generalizability
+5. Verify with other sources
+
+**Before applying ideas:**
+1. Map context similarities/differences
+2. Identify adaptation requirements
+3. Consider failure modes
+4. Start with small experiments
+5. Build feedback mechanisms
+
+**When uncertain:**
+1. State your uncertainties explicitly
+2. Identify what would resolve them
+3. Estimate confidence levels
+4. Plan validation steps
+5. Remain open to revision

references/critical-questions.md

@@ -0,0 +1,166 @@
+# Critical Questions by Document Type
+
+This reference provides type-specific questions for Third Pass critical analysis. Use these to supplement the universal questions in SKILL.md.
+
+## Tech Blog
+
+**Core Analysis:**
+- What problem does this solve, and for whom?
+- What are the trade-offs of this solution vs alternatives?
+- What's the assumed technical environment (stack, scale, team size)?
+- How would this approach fail or scale poorly?
+
+**Design & Implementation:**
+- Why this approach instead of simpler alternatives?
+- What are the hidden costs (complexity, maintenance, performance)?
+- What edge cases or error scenarios are not addressed?
+- How testable/debuggable is this approach?
+
+**Applicability:**
+- What prerequisites or constraints does this assume?
+- How well does this generalize to other contexts?
+- What would need to change for my use case?
+- Are there better-suited alternatives for my situation?
+
+**Evidence Quality:**
+- Are benchmarks/metrics provided? Are they representative?
+- Is there production experience or just prototypes?
+- What's missing from the evaluation?
+
+## Retrospective
+
+**Context & Validity:**
+- What was the specific context (team, org, timeline, constraints)?
+- How much is success due to approach vs context/luck?
+- Would this work in a different setting? Which aspects are transferable?
+
+**Lessons & Generalization:**
+- Are lessons backed by specific evidence or anecdotal?
+- What's the sample size (one project, multiple iterations)?
+- Are there alternative explanations for outcomes?
+- What would have happened with different decisions?
+
+**Missing Perspectives:**
+- What didn't work that isn't mentioned?
+- Who else was involved? What's their perspective?
+- What conflicts or tensions were glossed over?
+- What failed attempts preceded success?
+
+**Temporal Factors:**
+- When was this? Are lessons still valid?
+- How has the landscape changed since then?
+- What would be different if done today?
+
+## Technical Documentation
+
+**Design & Rationale:**
+- What design philosophy underlies this approach?
+- Why these abstractions vs alternatives?
+- What trade-offs were made (flexibility vs simplicity, etc.)?
+- What's explicitly not supported, and why?
+
+**Completeness & Accuracy:**
+- What common use cases are not documented?
+- Are there undocumented edge cases or gotchas?
+- Is error handling clearly explained?
+- What's the migration/upgrade story?
+
+**Context & Constraints:**
+- What assumptions about usage patterns?
+- What scale/performance characteristics?
+- What dependencies or prerequisites?
+- What's the intended audience expertise level?
+
+**Alternatives & Ecosystem:**
+- How does this compare to competing approaches?
+- What problems does this NOT solve well?
+- When should you use something else?
+
+## Personal Writing
+
+**Argument Structure:**
+- What's the core thesis or claim?
+- Is the claim clearly stated or implicit?
+- What evidence supports each point?
+- Are there logical gaps or leaps?
+
+**Assumptions & Biases:**
+- What's taken for granted without justification?
+- What perspectives or counterarguments are missing?
+- Are there hidden biases in framing?
+- What's the assumed audience knowledge?
+
+**Clarity & Coherence:**
+- Is the argument easy to follow?
+- Do examples actually support the points?
+- Are terms used consistently?
+- Is the conclusion justified by the body?
+
+**Rigor & Evidence:**
+- Are claims supported by evidence or assertion?
+- Are sources credible and relevant?
+- Are alternative explanations considered?
+- What would strengthen this argument?
+
+**Practical Application:**
+- Is this actionable or purely theoretical?
+- Who benefits from these ideas?
+- What's needed to implement these suggestions?
+- What could go wrong in practice?
+
+## Academic Paper
+
+**Research Design:**
+- Are research questions clearly stated?
+- Is methodology appropriate for questions?
+- Are there confounding variables not controlled?
+- Is sample size adequate and representative?
+- Could results be explained differently?
+
+**Assumptions & Validity:**
+- What theoretical assumptions underlie this work?
+- Are measurements valid for constructs?
+- Are there threats to internal/external validity?
+- How replicable is this research?
+
+**Related Work:**
+- Is related work comprehensive and fair?
+- What relevant prior work is missing?
+- How does this advance beyond existing work?
+- Are comparisons appropriate and fair?
+
+**Results & Interpretation:**
+- Do conclusions follow from results?
+- Are alternative interpretations possible?
+- Is statistical significance practical significance?
+- What are limitations and boundary conditions?
+
+**Contribution & Impact:**
+- What's genuinely novel here?
+- Is contribution incremental or significant?
+- What future research does this enable?
+- What are real-world applications?
+
+## Cross-Cutting Questions
+
+These apply to all document types:
+
+**Authority & Credibility:**
+- What's the author's expertise in this area?
+- What potential conflicts of interest exist?
+- Is tone confident or overconfident?
+
+**Temporal Context:**
+- When was this written?
+- What was the state of the field then?
+- What's changed since publication?
+
+**Rhetorical Choices:**
+- What's emphasized vs downplayed?
+- What language choices reveal assumptions?
+- What's the intended audience and purpose?
+
+**Actionability:**
+- What can I do with this information?
+- What would I need to verify before using this?
+- What risks come with applying this?

references/reconstruction-guide.md

@@ -0,0 +1,241 @@
+# Reconstruction Guide
+
+This reference provides detailed techniques for demonstrating deep understanding through reconstruction.
+
+## Purpose of Reconstruction
+
+Reconstruction is the ultimate test of understanding. If you can reconstruct the core ideas without reference to the source, explain them to someone else, and identify how they apply to your context, you've truly understood.
+
+## Reconstruction Techniques
+
+### 1. Mental Re-implementation
+
+**For technical content:**
+- Close the document and explain the approach from memory
+- Draw diagrams or write pseudocode from scratch
+- Identify what information you need to look up vs what you remember
+- Explain why each component exists and how they fit together
+
+**For conceptual content:**
+- State the main argument in your own words
+- Rebuild the logical flow from first principles
+- Identify key insights vs supporting details
+- Explain the "why" behind each claim
+
+### 2. Teaching Test
+
+Imagine explaining this to someone with different background:
+
+**To a beginner:**
+- What analogies would you use?
+- What examples would clarify complex points?
+- What prerequisites need explanation?
+- Where would confusion likely arise?
+
+**To an expert in different domain:**
+- What core principles transfer?
+- What domain-specific jargon needs translation?
+- What parallels exist in their field?
+
+### 3. Critical Comparison
+
+**Against your prior understanding:**
+- What did you believe before?
+- What changed your thinking?
+- What remains uncertain?
+- What conflicts with other knowledge?
+
+**Against alternative approaches:**
+- How would someone with different philosophy approach this?
+- What would a skeptic question?
+- What would an enthusiast emphasize?
+
+### 4. Contextual Translation
+
+**To your specific situation:**
+
+**Direct application:**
+- What can you use exactly as presented?
+- What problems of yours does this solve?
+- What resources do you have that the author didn't?
+
+**Required adaptation:**
+- What needs modification for your context?
+- What constraints do you have that differ?
+- What would you simplify or elaborate?
+- What risks are specific to your situation?
+
+**Not applicable:**
+- What doesn't fit your situation?
+- Why not? (constraints, scale, goals, environment)
+- What would you do instead?
+- What can you learn from this even if not applicable?
+
+### 5. Stress Testing
+
+**Push the ideas to boundaries:**
+- What happens at extreme scale?
+- What if key assumptions don't hold?
+- What if opposite approach was taken?
+- What corner cases break this?
+
+**Identify fragility:**
+- Where is this most likely to fail?
+- What makes it robust or brittle?
+- What failure modes are hidden?
+- What early warning signs would indicate problems?
+
+## Reconstruction Checklist
+
+Verify your understanding by confirming you can:
+
+- [ ] State core ideas without referencing source
+- [ ] Explain why approach makes sense (not just what it is)
+- [ ] Draw diagrams or structure from memory
+- [ ] Identify what would change in different contexts
+- [ ] Explain to someone with different background
+- [ ] Critique the approach intelligently
+- [ ] Generate examples not in original
+- [ ] Identify related concepts or approaches
+- [ ] Predict what author would say about edge cases
+- [ ] Apply insights to your own problems
+
+## Common Pitfalls
+
+**Surface-level paraphrasing:**
+- Rewording original sentences without deep processing
+- Changing vocabulary but keeping same structure
+- Memorizing examples instead of understanding principles
+
+**Missing implicit knowledge:**
+- Assuming author's background knowledge
+- Not questioning unstated assumptions
+- Missing contextual factors
+
+**Overgeneralization:**
+- Applying lessons beyond valid scope
+- Ignoring boundary conditions
+- Assuming universal applicability
+
+**Undergeneralization:**
+- Treating as one-off solution
+- Missing transferable principles
+- Not abstracting core insights
+
+## Reconstruction Strategies by Type
+
+### Tech Blog
+
+**Key elements to reconstruct:**
+- Problem definition and constraints
+- Solution architecture (draw from memory)
+- Why this approach vs alternatives
+- Implementation considerations
+- Where approach would fail
+
+**Validation:**
+- Can you implement core idea without referencing?
+- Can you explain trade-offs to teammate?
+- Can you identify when to use vs avoid?
+
+### Retrospective
+
+**Key elements to reconstruct:**
+- Context and constraints
+- What happened (timeline)
+- Why outcomes occurred (causal analysis)
+- Lessons and their applicability boundaries
+- Your interpretation vs author's
+
+**Validation:**
+- Can you teach lessons to your team?
+- Can you identify what's context-dependent?
+- Can you predict when lessons apply?
+
+### Technical Documentation
+
+**Key elements to reconstruct:**
+- Design philosophy and rationale
+- Core abstractions and relationships
+- Common patterns and anti-patterns
+- Edge cases and error handling
+- When to use this vs alternatives
+
+**Validation:**
+- Can you use API/system without docs?
+- Can you explain design decisions?
+- Can you troubleshoot problems independently?
+
+### Personal Writing
+
+**Key elements to reconstruct:**
+- Central argument and support
+- Logical flow and structure
+- Key insights vs supporting details
+- Author's assumptions and perspective
+- Your critical response
+
+**Validation:**
+- Can you steelman the argument?
+- Can you articulate disagreements clearly?
+- Can you extract actionable insights?
+
+### Academic Paper
+
+**Key elements to reconstruct:**
+- Research question and motivation
+- Methodology and rationale
+- Key results and implications
+- Limitations and future work
+- How this advances the field
+
+**Validation:**
+- Can you explain to non-expert?
+- Can you identify follow-up experiments?
+- Can you critique methodology intelligently?
+
+## Output Format
+
+Structure reconstruction output to show depth:
+
+```markdown
+#### Reconstruction
+
+> [!Abstract] Core Ideas in Own Words
+> [Main thesis without referencing source]
+>
+> [Key supporting concepts - explain the "why"]
+>
+> [How pieces fit together - the mental model]
+
+> [!Example] Application to My Context
+> **Direct application:**
+> - [What I can use as-is and why it fits]
+>
+> **Requires adaptation:**
+> - [What needs changing and how I'd modify it]
+> - [Why changes are necessary for my context]
+>
+> **Not applicable:**
+> - [What doesn't fit and why]
+> - [What I'd do instead and reasoning]
+```
+
+## Advanced Reconstruction
+
+### Meta-Cognitive Layer
+
+Go beyond content to process:
+- Why did author choose this presentation?
+- What's the intended reader journey?
+- What rhetorical strategies are used?
+- What would you have done differently?
+
+### Generative Understanding
+
+True mastery enables generation:
+- Create new examples applying principles
+- Extend ideas to new domains
+- Identify implications not stated
+- Generate hypotheses to test
+- Connect to other frameworks