zhongwei/gh-lyndonkl-claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:38:26 +08:00
commit 41d9f6b189
304 changed files with 98322 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
skills/abstraction-concrete-examples/resources/examples/api-design.md Normal file
View File

@@ -0,0 +1,139 @@
# Abstraction Ladder Example: API Design
## Topic: RESTful API Design
## Overview
This ladder shows how abstract API design principles translate into concrete implementation decisions for a user management endpoint.
## Abstraction Levels
### Level 1 (Most Abstract): Universal Principle
**"Interfaces should be intuitive, consistent, and predictable"**
This applies to all interfaces: APIs, UI, command-line tools, hardware controls. Users should be able to predict behavior based on consistent patterns.
### Level 2: Framework & Standards
**"Follow REST architectural constraints and HTTP semantics"**
RESTful design provides standardized patterns:
- Resources identified by URIs
- Stateless communication
- Standard HTTP methods (GET, POST, PUT, DELETE)
- Appropriate status codes
- HATEOAS (where applicable)
### Level 3: Approach & Patterns
**"Design resource-oriented endpoints with predictable CRUD operations"**
Concrete patterns:
- Use nouns for resources, not verbs
- Plural resource names
- Nested resources show relationships
- Query parameters for filtering/pagination
- Consistent error response format
### Level 4: Specific Implementation
**"User management API with standard CRUD endpoints"**
```
GET /api/v1/users # List all users
GET /api/v1/users/:id # Get specific user
POST /api/v1/users # Create user
PUT /api/v1/users/:id # Update user (full)
PATCH /api/v1/users/:id # Update user (partial)
DELETE /api/v1/users/:id # Delete user
```
Authentication: Bearer token in Authorization header
Content-Type: application/json
### Level 5 (Most Concrete): Precise Details
**Exact endpoint specification:**
```http
GET /api/v1/users/12345
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json
Response: 200 OK
{
"id": 12345,
"email": "user@example.com",
"firstName": "Jane",
"lastName": "Doe",
"createdAt": "2024-01-15T10:30:00Z",
"role": "standard"
}
Edge cases:
- User not found: 404 Not Found
- Invalid token: 401 Unauthorized
- Insufficient permissions: 403 Forbidden
- Invalid ID format: 400 Bad Request
- Server error: 500 Internal Server Error
```
Rate limit: 1000 requests/hour per token
Pagination: max 100 items per page, default 20
## Connections & Transitions
**L1 → L2**: REST provides a proven framework for creating predictable interfaces through standard conventions.
**L2 → L3**: Resource-oriented design is how REST constraints manifest in practical API design.
**L3 → L4**: User management is a concrete application of CRUD patterns to a specific domain resource.
**L4 → L5**: Exact HTTP requests/responses and error handling show how design patterns become actual code.
## Edge Cases & Boundary Testing
### Case 1: Deleting a non-existent user
- **Abstract principle (L1)**: Interface should provide clear feedback
- **Expected (L3)**: Return error for invalid operations
- **Actual (L5)**: `DELETE /users/99999` returns `404 Not Found` with body `{"error": "User not found"}`
- **Alignment**: ✓ Concrete implementation matches principle
### Case 2: Updating with partial data
- **Abstract principle (L1)**: Interface should be predictable
- **Expected (L3)**: PATCH for partial updates, PUT for full replacement
- **Actual (L5)**: `PATCH /users/123` with `{"firstName": "John"}` updates only firstName, leaves other fields unchanged
- **Alignment**: ✓ Follows REST semantics
### Case 3: Bulk operations
- **Abstract principle (L1)**: Interfaces should be consistent
- **Question**: How to delete multiple users?
- **Options**:
- POST /users/bulk-delete (violates resource-oriented design)
- DELETE /users with query params (non-standard)
- Multiple DELETE requests (chatty but consistent)
- **Gap**: Pure REST doesn't handle bulk operations elegantly
- **Resolution**: Accept trade-off; use `POST /users/actions/bulk-delete` with clear documentation
## Applications
This ladder is useful for:
- **Onboarding new developers**: Show how design principles inform specific code
- **API review**: Check if implementation aligns with stated principles
- **Documentation**: Explain "why" behind specific endpoint designs
- **Consistency checking**: Ensure new endpoints follow same patterns
- **Client SDK design**: Derive SDK structure from abstraction levels
## Gaps & Assumptions
**Assumptions:**
- Using JSON (could be XML, Protocol Buffers, etc.)
- Token-based auth (could be OAuth, API keys, etc.)
- Synchronous operations (could be async/webhooks)
**Gaps:**
- Real-time updates not covered (WebSockets?)
- File uploads not addressed (multipart/form-data?)
- Versioning strategy mentioned but not detailed
- Caching strategy not specified
- Bulk operations awkward in pure REST
**Questions for deeper exploration:**
- How do GraphQL or gRPC change this ladder?
- What happens at massive scale (millions of requests/sec)?
- How does distributed/microservices architecture affect this?

194
skills/abstraction-concrete-examples/resources/examples/hiring-process.md Normal file
View File

@@ -0,0 +1,194 @@
# Abstraction Ladder Example: Hiring Process
## Topic: Building an Effective Hiring Process
## Overview
This ladder demonstrates how abstract hiring principles translate into concrete interview procedures. Built bottom-up from actual hiring experiences.
## Abstraction Levels
### Level 5 (Most Concrete): Specific Example
**Tuesday interview for Senior Engineer position:**
- 9:00 AM: Recruiter sends calendar invite with Zoom link
- 10:00 AM: 45-min technical interview
- Candidate shares screen
- Interviewer asks: "Design a URL shortening service"
- Candidate discusses for 30 min while drawing architecture
- 10 min for candidate questions
- Interviewer fills scorecard: System Design=4/5, Communication=5/5
- 11:00 AM: Candidate receives thank-you email
- 11:30 AM: Interviewer submits scores in Greenhouse ATS
- Week later: Debrief meeting reviews 6 scorecards, makes hire/no-hire decision
**Specific scoreboard criteria:**
- Problem solving: 1-5 scale
- Communication: 1-5 scale
- Culture fit: 1-5 scale
- Technical depth: 1-5 scale
- Bar raiser must approve (score ≥4 average)
### Level 4: Implementation Pattern
**Structured interview loop with standardized evaluation**
Process:
1. Phone screen (30 min) - basic qualification
2. Take-home assignment (2-4 hours) - practical skills
3. Onsite loop (4-5 hours):
- Technical interview #1: System design
- Technical interview #2: Coding
- Behavioral interview: Past experience
- Hiring manager: Role fit & vision alignment
- Optional: Team member lunch (informal)
4. Debrief within 48 hours
5. Reference checks for strong candidates
6. Offer or rejection with feedback
Each interviewer:
- Uses structured scorecard
- Submits written feedback within 24 hours
- Rates on consistent rubric
- Provides hire/no-hire recommendation
### Level 3: Approach & Method
**Use structured interviews with job-relevant assessments and multiple evaluators**
Key practices:
- Define role requirements before interviews
- Create standardized questions for each competency
- Train interviewers on bias and evaluation
- Use panel of diverse interviewers
- Evaluate on job-specific skills, not proxies
- Aggregate independent ratings before discussion
- Check references to validate assessments
- Provide candidate feedback regardless of outcome
### Level 2: Framework & Research
**Apply evidence-based hiring practices to reduce bias and improve predictive validity**
Research-backed principles:
- Structured interviews outperform unstructured (Schmidt & Hunter meta-analysis)
- Work samples better predict performance than credentials
- Multiple independent evaluators reduce individual bias
- Job analysis identifies actual success criteria
- Standardization enables fair comparisons
- Cognitive diversity in hiring panels improves decisions
Standards to follow:
- EEOC guidelines for non-discrimination
- GDPR/privacy compliance for candidate data
- Industry best practices (e.g., SHRM)
### Level 1 (Most Abstract): Universal Principle
**"Hiring should identify candidates most likely to succeed while treating all applicants fairly and respectfully"**
Core values:
- Meritocracy: Select based on ability to do the job
- Equity: Provide equal opportunity regardless of background
- Predictive validity: Assessments should predict actual job performance
- Candidate experience: Treat people with dignity
- Continuous improvement: Learn from outcomes to refine process
This applies beyond hiring to any selection process: admissions, promotions, awards, grants, etc.
## Connections & Transitions
**L5 → L4**: The specific Tuesday interview exemplifies the structured interview loop approach. Each element (scorecard, timing, Greenhouse submission) reflects the systematic pattern.
**L4 → L3**: The structured loop implements the principle of using job-relevant assessments with multiple evaluators. The 48-hour debrief and standardized scorecards are concrete applications of standardization.
**L3 → L2**: Structured interviews and work samples are the practical application of "evidence-based hiring practices" from I/O psychology research.
**L2 → L1**: Evidence-based practices are how we operationalize the abstract values of merit, equity, and predictive validity.
## Edge Cases & Boundary Testing
### Case 1: Candidate has unconventional background
- **Abstract principle (L1)**: Hire based on merit and ability
- **Standard process (L4)**: Looking for "5+ years experience with React"
- **Edge case**: Candidate has 2 years React but exceptional work sample and adjacent skills
- **Tension**: Strict requirements vs. actual capability
- **Resolution**: Requirements are proxy for skills; assess skills directly through work sample
### Case 2: All interviewers are available except one
- **Abstract principle (L1)**: Multiple evaluators reduce bias
- **Standard process (L3)**: Panel of diverse interviewers
- **Edge case**: Only senior engineers available this week, no product manager
- **Tension**: Speed vs. diverse perspectives
- **Resolution**: Delay one week to get proper panel, or explicitly note missing perspective in decision
### Case 3: Internal referral from CEO
- **Abstract principle (L1)**: Treat all applicants fairly
- **Standard process (L4)**: All candidates go through same loop
- **Edge case**: CEO's referral puts pressure to hire
- **Tension**: Political dynamics vs. process integrity
- **Resolution**: Use same process but ensure bar raiser is involved; separate "good referral" from "strong candidate"
### Case 4: Candidate requests accommodation
- **Abstract principle (L1)**: Treat people with dignity and respect
- **Standard process (L4)**: 45-min technical interview with live coding
- **Edge case**: Candidate has dyslexia, requests written questions in advance
- **Tension**: Standardization vs. accessibility
- **Resolution**: Accommodation maintains what we're testing (problem-solving) while removing irrelevant barrier (reading speed). Provide questions 30 min before; maintain time limit.
## Applications
This ladder is useful for:
**For hiring managers:**
- Design new interview process grounded in principles
- Explain to candidates why process is structured this way
- Train new interviewers on the "why" behind each step
**For executives:**
- Understand ROI of structured hiring (L1-L2)
- Make resource decisions (time investment in L4-L5)
**For candidates:**
- Understand what to expect and why
- See how specific interview ties to broader goals
**For process improvement:**
- Identify where implementation (L5) drifts from principles (L1)
- Test if new tools/techniques align with evidence base (L2)
## Gaps & Assumptions
**Assumptions:**
- Hiring for full-time employee role (not contractor/intern)
- Mid-size tech company context (not 10-person startup or Fortune 500)
- White-collar knowledge work (not frontline/manual labor)
- North American legal/cultural context
- Sufficient candidate volume to justify structure
**Gaps:**
- Doesn't address compensation negotiation
- Doesn't detail sourcing/recruiting before application
- Doesn't specify onboarding after hire
- Limited discussion of diversity/inclusion initiatives
- Doesn't address remote vs. in-person trade-offs
- No mention of employer branding
**What changes at different scales:**
- **Startup (10 people)**: Might skip structured scorecards (everyone knows everyone)
- **Enterprise (10,000 people)**: Might add compliance reviews, more stakeholders
- **High-volume hiring**: Might add automated screening, assessment centers
**What changes in different domains:**
- **Trades/manual labor**: Work samples would be actual task performance
- **Creative roles**: Portfolio review more important than interviews
- **Executive roles**: Board involvement, longer timeline, reference checks crucial
## Lessons Learned
**Principle that held up:**
The core idea (L1) of "fair and predictive" remains true even when implementation (L5) varies wildly by context.
**Principle that required nuance:**
"Multiple evaluators" (L3) assumes independence. In practice, first interviewer's opinion can bias later interviewers. Solution: collect ratings before debrief discussion.
**Missing level:**
Could add L2.5 for company-specific values ("hire for culture add, not culture fit"). Shows how universal principles get customized before becoming process.
**Alternative ladder:**
Could build parallel ladder for "candidate experience" that shows how to treat applicants well. Would share L1 but diverge at L2-L5 with different practices (clear communication, timely feedback, etc.).