blindspot-pass

Files (1)

• SKILL.md

SKILL.md (first lines)

# Blind Spot Pass

## When to Use

Use this skill **before starting implementation** when:
- Working on an unfamiliar part of the codebase
- Integrating with systems you don't fully understand
- The task has high stakes or complexity
- You sense there might be hidden gotchas

## What It Does

A blind spot pass helps identify **unknown unknowns** that could derail implementation or lead to poor architectural decisions.

## How to Execute

### Step 1: Define Scope

Clearly state what you're about to work on:
- Feature or change description
- Affected modules/systems
- Current understanding level

### Step 2: Search for Context

Look in multiple places for relevant history:

```bash
# Recent changes to related files
git log --oneline --all -20 -- path/to/module/

# Search commit messages for keywords
git log --all --grep="auth\|oauth\|provider" --oneline

# Find related discussions in code comments
rg -i "TODO|FIXME|HACK|XXX" path/to/module/

# Search for error handling patterns
rg "catch|throw|error" path/to/module/ -A 3
```

### Step 3: Identify Gotchas

Document findings in categories:

**Technical Gotchas**:
- Edge cases in existing code
- Performance considerations
- Error handling patterns
- Testing requirements

**Architectural Gotchas**:
- Existing abstractions to follow
- Integration points
- Data flow patterns
- State management approaches

**Business Gotchas**:
- Implicit requirements from past discussions
- Feature flags or phased rollouts
- Backward compatibility needs
- Security or compliance requirements

### Step 4: Surface Questions

Generate questions that would change the approach:

- "I see error handling uses X pattern; should I follow it?"
- "There's a feature flag system; does this need one?"
- "Previous auth work had Y consideration; does that apply here?"

### Step 5: Present Findings

Format as a structured report:

```markdown
## Blind Spot Analysis: [Task Name]

### Context Sources Checked
- [x] Git history (last 3 months, 45 commits in auth/)
- [x] Code comments and TODOs (found 3 relevant)
- [x] Error handling patterns (uses Result type)
- [x] Test coverage (integration tests in /tests/auth/)

### Key Findings

**Architectural Patterns**:
- All auth providers extend BaseOAuthProvider
- Must implement 3 lifecycle hooks: init, authenticate, refresh
- Config validation happens at provider registration

**Known Gotchas**:
- GitHub OAuth requires app installation per org (not per user)
- Refresh tokens expire after 6 months of inactivity
- Rate limiting uses Redis; need to handle connection failures

**Testing Requirements**:
- Mock responses in tests/fixtures/oauth/
- Integration tests use test credentials from .env.test
- Must test token refresh flow explicitly

### Questions Before Proceeding

1. Should GitHub provider support org-level installation?
2. How should we handle rate limit failures? (retry? user error?)
3. Is there a preferred library for GitHub OAuth, or implement from scratch?

### Recommended Approach

[Brief recommendation based on findings]
```

## Example Usage

```
User: "I need to add Stripe payment integration to our checkout flow"

Agent: "Let me do a blind spot pass first to identify unknowns."

From jellydn/my-ai-tools, MIT.

More from jellydn/my-ai-tools