Initial commit

2025-11-30 08:38:26 +08:00
commit 41d9f6b189
304 changed files with 98322 additions and 0 deletions
--- a/skills/abstraction-concrete-examples/resources/methodology.md
+++ b/skills/abstraction-concrete-examples/resources/methodology.md
@@ -0,0 +1,356 @@
+# Abstraction Ladder Methodology
+
+## Abstraction Ladder Workflow
+
+Copy this checklist and track your progress:
+
+```
+Abstraction Ladder Progress:
+- [ ] Step 1: Choose your direction (top-down, bottom-up, or middle-out)
+- [ ] Step 2: Build each abstraction level
+- [ ] Step 3: Validate transitions between levels
+- [ ] Step 4: Test with edge cases
+- [ ] Step 5: Verify coherence and completeness
+```
+
+**Step 1: Choose your direction**
+
+Select the approach that fits your purpose. See [Choosing the Right Direction](#choosing-the-right-direction) for detailed guidance on top-down, bottom-up, or middle-out approaches.
+
+**Step 2: Build each abstraction level**
+
+Create 3-5 distinct levels following quality criteria for each level type. See [Building Each Level](#building-each-level) for characteristics and quality checks for universal principles, frameworks, methods, implementations, and precise details.
+
+**Step 3: Validate transitions**
+
+Ensure each level logically derives from the previous one. See [Validating Transitions](#validating-transitions) for transition tests and connection patterns.
+
+**Step 4: Test with edge cases**
+
+Test your abstraction ladder against boundary scenarios to reveal gaps or conflicts. See [Edge Case Discovery](#edge-case-discovery) for techniques to find and analyze edge cases.
+
+**Step 5: Verify coherence and completeness**
+
+Check that the ladder flows as a coherent whole and covers the necessary scope. See [Common Pitfalls](#common-pitfalls) and [Advanced Techniques](#advanced-techniques) for validation approaches.
+
+## Choosing the Right Direction
+
+### Top-Down (Abstract → Concrete)
+
+**When to use:**
+- Communicating established principles to new audience
+- Designing systems from first principles
+- Teaching theoretical concepts
+- Creating implementation from requirements
+
+**Process:**
+1. Start with the most universal, broadly applicable statement
+2. Ask "How would this manifest in practice?"
+3. Add constraints and context at each level
+4. End with specific, measurable examples
+
+**Example flow:**
+- Level 1: "Software should be maintainable"
+- Level 2: "Use modular architecture and clear interfaces"
+- Level 3: "Implement dependency injection and single responsibility principle"
+- Level 4: "UserService has one public method `getUser(id)` with IUserRepository injected"
+- Level 5: "Line 47: `constructor(private repository: IUserRepository) {}`"
+
+### Bottom-Up (Concrete → Abstract)
+
+**When to use:**
+- Analyzing existing implementations
+- Discovering patterns from observations
+- Generalizing from specific cases
+- Root cause analysis
+
+**Process:**
+1. Start with specific, observable facts
+2. Ask "What pattern does this exemplify?"
+3. Remove context-specific details at each level
+4. End with universal principles
+
+**Example flow:**
+- Level 5: "GET /api/users/123 returns 404 when user doesn't exist"
+- Level 4: "API returns appropriate HTTP status codes for resource states"
+- Level 3: "REST API follows HTTP semantic conventions"
+- Level 2: "System communicates errors consistently through standard protocols"
+- Level 1: "Interfaces should provide clear, unambiguous feedback"
+
+### Middle-Out (Familiar → Both Directions)
+
+**When to use:**
+- Starting with something stakeholders understand
+- Bridging technical and business perspectives
+- Teaching from known to unknown
+
+**Process:**
+1. Start at a familiar, mid-level example
+2. Expand upward to extract principles
+3. Expand downward to show implementation
+4. Ensure both directions connect coherently
+
+## Building Each Level
+
+### Level 1: Universal Principles
+
+**Characteristics:**
+- Applies across domains and contexts
+- Value-based or theory-driven
+- Often uses terms like "should," "must," "always"
+- Could apply to different industries/fields
+
+**Quality check:**
+- Can you apply this to a completely different domain?
+- Is it so abstract it's almost philosophical?
+- Does it express fundamental values or laws?
+
+**Examples:**
+- "Systems should be resilient to failure"
+- "Users deserve privacy and control over their data"
+- "Organizations should optimize for long-term value"
+
+### Level 2: Categories & Frameworks
+
+**Characteristics:**
+- Organizes the domain into conceptual buckets
+- References established frameworks or standards
+- Defines high-level approaches
+- Still domain-general but more specific
+
+**Quality check:**
+- Does it reference a framework others would recognize?
+- Could practitioners cite this as a "best practice"?
+- Is it general enough to apply across similar projects?
+
+**Examples:**
+- "Follow SOLID principles for object-oriented design"
+- "Implement defense-in-depth security strategy"
+- "Use Agile methodology for iterative development"
+
+### Level 3: Methods & Approaches
+
+**Characteristics:**
+- Actionable techniques and methods
+- Still flexible in implementation
+- Describes "how" in general terms
+- Multiple valid implementations possible
+
+**Quality check:**
+- Could two teams implement this differently but both be correct?
+- Does it guide action without dictating exact steps?
+- Can you name 3+ ways to implement this?
+
+**Examples:**
+- "Use dependency injection for loose coupling"
+- "Implement rate limiting to prevent abuse"
+- "Create user personas based on research interviews"
+
+### Level 4: Specific Instances
+
+**Characteristics:**
+- Concrete implementations
+- Project or context-specific
+- References actual code, designs, or artifacts
+- Limited variation in implementation
+
+**Quality check:**
+- Could you point to this in a codebase or document?
+- Is it specific to one project/product?
+- Would changing this require actual work (not just thinking)?
+
+**Examples:**
+- "AuthService uses JWT tokens with 1-hour expiration"
+- "Dashboard loads user data via GraphQL endpoint"
+- "Button uses 16px padding and #007bff background"
+
+### Level 5: Precise Details
+
+**Characteristics:**
+- Measurable, verifiable specifics
+- Exact values, configurations, line numbers
+- Edge cases and boundary conditions
+- No ambiguity in interpretation
+
+**Quality check:**
+- Can you measure or test this objectively?
+- Is there exactly one interpretation?
+- Could QA write a test case from this?
+
+**Examples:**
+- "Line 234: `if (userId < 1 || userId > 2147483647) throw RangeError`"
+- "Button #submit-btn has tabindex=0 and aria-label='Submit form'"
+- "Password must be 8-72 chars, including: a-z, A-Z, 0-9, !@#$%"
+
+## Validating Transitions
+
+### Connection Tests
+
+For each adjacent pair of levels, verify:
+
+1. **Derivation**: Can you logically derive the lower level from the higher level?
+   - Ask: "Does this concrete example truly exemplify that abstract principle?"
+
+2. **Generalization**: Can you extract the higher level from the lower level?
+   - Ask: "If I saw only this concrete example, would I infer that principle?"
+
+3. **No jumps**: Is the gap between levels small enough to follow?
+   - Ask: "Can I explain the transition without introducing entirely new concepts?"
+
+### Red Flags
+
+- **Too similar**: Two levels say essentially the same thing
+- **Missing middle**: Big conceptual leap between levels
+- **Contradiction**: Concrete example violates abstract principle
+- **Jargon shift**: Different terminology without translation
+- **Context switch**: Levels address different aspects of the topic
+
+## Edge Case Discovery
+
+Edge cases are concrete scenarios that test the boundaries of abstract principles.
+
+### Finding Edge Cases
+
+1. **Boundary testing**: What happens at extremes?
+   - Zero, negative, maximum values
+   - Empty sets, single items, massive scale
+   - Start/end of time ranges
+
+2. **Contradiction hunting**: When does the principle not apply?
+   - Special circumstances
+   - Conflicting principles
+   - Trade-offs that force compromise
+
+3. **Real-world friction**: What makes implementation hard?
+   - Technical limitations
+   - Business constraints
+   - User behavior
+   - Legacy systems
+
+### Documenting Edge Cases
+
+For each edge case, document:
+- **Scenario**: Specific concrete situation
+- **Expectation**: What abstract principle suggests should happen
+- **Reality**: What actually happens
+- **Gap**: Why there's a difference
+- **Resolution**: How to handle it
+
+**Example:**
+- **Scenario**: User uploads 5GB profile photo
+- **Expectation**: "System should accept user input" (abstract principle)
+- **Reality**: Server rejects file > 10MB
+- **Gap**: Principle doesn't account for resource limits
+- **Resolution**: Revise principle to "System should accept reasonable user input within documented constraints"
+
+## Common Pitfalls
+
+### 1. Fake Concreteness
+
+**Problem**: Using specific-sounding language without actual specificity.
+
+**Bad**: "The system should have good performance"
+**Good**: "The system should respond to API requests in < 200ms at p95"
+
+### 2. Missing the Abstract
+
+**Problem**: Starting too concrete, never reaching universal principles.
+
+**Bad**: Levels 1-5 all describe different API endpoints
+**Good**: Extract what makes a "good API" from those endpoints
+
+### 3. Inconsistent Granularity
+
+**Problem**: Some levels are finely divided, others make huge jumps.
+
+**Fix**: Ensure roughly equal conceptual distance between all adjacent levels.
+
+### 4. Topic Drift
+
+**Problem**: Different levels address different aspects of the topic.
+
+**Bad**:
+- Level 1: "Software should be secure"
+- Level 2: "Use encryption for data"
+- Level 3: "Users prefer simple interfaces" ← Drift!
+
+**Good**: Keep all levels on the same thread (security, in this case).
+
+### 5. Over-specification
+
+**Problem**: Making higher levels too specific too early.
+
+**Bad**: Level 1: "React apps should use Redux Toolkit"
+**Good**: Level 1: "Applications should manage state predictably"
+
+## Advanced Techniques
+
+### Multiple Ladders
+
+For complex topics, create multiple parallel ladders for different aspects:
+
+**Topic: E-commerce Checkout**
+- Ladder A: Security (data protection → PCI compliance → specific encryption)
+- Ladder B: UX (easy purchase → progress indication → specific button placement)
+- Ladder C: Performance (fast checkout → async processing → specific caching strategy)
+
+### Ladder Mapping
+
+Connect ladders at various levels to show relationships:
+
+```
+Ladder A (Feature):          Ladder B (Architecture):
+L1: Improve user engagement ← L1: System should be modular
+L2: Add social features     ← L2: Use microservices
+L3: Implement commenting    ← L3: Comment service
+L4: POST /comments endpoint ← L4: Express.js REST API
+```
+
+### Audience Targeting
+
+Create the same ladder with different emphasis for different audiences:
+
+**For executives**: Focus on levels 1-2 (strategy, ROI)
+**For managers**: Focus on levels 2-3 (approach, methods)
+**For engineers**: Focus on levels 3-5 (implementation, details)
+
+### Reverse Engineering
+
+Take existing concrete work and extract the abstraction ladder:
+1. Document exactly what was built (Level 5)
+2. Ask "Why this specific implementation?" (Level 4)
+3. Ask "What approach guided this?" (Level 3)
+4. Continue upward to principles
+
+This reveals:
+- Implicit assumptions
+- Unstated principles
+- Gaps between intent and execution
+
+### Gap Analysis
+
+Compare ideal ladder vs. actual implementation:
+
+**Ideal**:
+- L1: "Products should be accessible"
+- L2: "Follow WCAG 2.1 AA"
+- L3: "All interactive elements keyboard navigable"
+
+**Actual**:
+- L5: "Some buttons missing tabindex"
+- Inference: Gap between L1 intention and L5 reality
+
+Use gap analysis to:
+- Identify technical debt
+- Find missing requirements
+- Plan improvements
+
+## Summary
+
+Effective abstraction ladders:
+- Have clear, logical transitions between levels
+- Cover both universal principles and specific details
+- Reveal assumptions and edge cases
+- Serve the user's actual need (communication, design, validation, etc.)
+
+Remember: The ladder is a tool for thinking and communicating, not an end in itself. Build what's useful for the task at hand.