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