gh-lyndonkl-claude/skills/abstraction-concrete-examples/resources/methodology.md

# 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.