Context Gathering Skill Skill

Context Gathering Skill

Core Principle: Understand before acting.

When to Invoke

Starting work in an unfamiliar codebase
Beginning a new feature implementation
Before modifying code you haven't worked with before
When requirements reference parts of the system you don't understand
After a context switch to a different area of the codebase

Exploration Protocol

Execute these phases in order. Do not skip phases.

Phase 1: Architecture

Objective: Build mental map of the system.

1. Read documentation:
   - README.md (project purpose, setup)
   - docs/ directory (if exists)
   - CONTRIBUTING.md (conventions)
   - ARCHITECTURE.md (if exists)

2. Identify entry points:
   - Main entry file (main.py, index.ts, etc.)
   - CLI entry points
   - API routes/handlers
   - Event handlers

3. Map directory structure:
   - What does each top-level directory contain?
   - Where does business logic live?
   - Where are tests?
   - Where is configuration?

Phase 2: Patterns

Objective: Understand existing conventions.

1. Find similar features:
   - Search for implementations like what you'll build
   - Note how they're structured
   - Identify reusable patterns

2. Identify coding conventions:
   - Naming patterns (camelCase, snake_case, etc.)
   - File organization (one class per file? grouped by feature?)
   - Error handling patterns
   - Logging patterns

3. Note test patterns:
   - Test file naming
   - Test structure (describe/it, test classes, etc.)
   - Mocking patterns
   - Test data patterns

Phase 3: Dependencies

Objective: Understand external connections.

1. Check dependency files:
   - package.json / requirements.txt / Cargo.toml / etc.
   - Lock files for exact versions

2. Identify external services:
   - Databases
   - APIs
   - Message queues
   - Cache systems

3. Note version constraints:
   - Language version requirements
   - Framework version requirements
   - Breaking change warnings

Phase 4: Document Findings

Objective: Create actionable summary.

Use the output template below to capture findings.

Output Template

After exploration, produce this structured summary:

context_gathering:
  timestamp: [ISO 8601]
  target: "[Area being explored]"

  project_understanding:
    purpose: |
      [What the project does - 1-2 sentences]
    architecture: |
      [How it's structured - key components and their relationships]
    tech_stack:
      - [Language/Framework 1]
      - [Language/Framework 2]

  relevant_files:
    entry_points:
      - path: [file path]
        purpose: [what it does]
    similar_implementations:
      - path: [file path]
        relevance: [why it's relevant to current task]
    test_examples:
      - path: [file path]
        pattern: [what pattern it demonstrates]

  conventions_noted:
    naming: "[pattern observed]"
    file_structure: "[pattern observed]"
    error_handling: "[pattern observed]"
    testing: "[pattern observed]"

  dependencies:
    internal:
      - "[Module/package this code depends on]"
    external:
      - name: "[package name]"
        version: "[version]"
        purpose: "[why it's used]"

  gaps_in_understanding:
    - "[Thing you couldn't figure out]"
    - "[Area that needs clarification]"

  confidence: 0.0
  evidence:
    - "[File read]"
    - "[Search performed]"

Exploration Checklist

Before proceeding to implementation, verify:

[ ] I know where to put new code
[ ] I found at least one similar implementation to reference
[ ] I understand the test patterns to follow
[ ] I identified all external dependencies relevant to my task
[ ] I documented any gaps in understanding
[ ] I have confidence >= 0.7 in my understanding

[!CRITICAL] If confidence < 0.7, DO NOT proceed to implementation. Either gather more context or escalate gaps to user.

Anti-Patterns

What NOT to Do

| Anti-Pattern | Problem | Instead | |--------------|---------|---------| | "I'll figure it out as I go" | Leads to inconsistent code | Complete exploration first | | Skipping documentation | Miss important constraints | Always check docs first | | Assuming conventions | Introduces inconsistency | Verify patterns in existing code | | Ignoring test patterns | Tests won't fit project style | Study existing tests | | Starting with implementation | May require extensive rework | Understand then implement |

Integration with Other Skills

| After Context Gathering | Invoke | |-------------------------|--------| | Ready to plan implementation | → writing-plans skill | | Multiple approaches identified | → orchestration skill to decompose | | Writing new code | → tdd skill |

Chaining Rules

ALWAYS complete context gathering before writing new code
IF gaps remain THEN ask user for clarification before proceeding
IF similar implementations found THEN reference them in your plan
AFTER context gathered THEN invoke writing-plans for implementation

Example

Task: "Add a new API endpoint for user preferences"

Context Gathering Output:

context_gathering:
  timestamp: "2024-01-15T10:30:00Z"
  target: "User preferences API endpoint"

  project_understanding:
    purpose: |
      REST API backend for user management application
    architecture: |
      Express.js with layered architecture: routes → controllers → services → repositories
    tech_stack:
      - Node.js 18
      - Express.js 4.x
      - PostgreSQL with Prisma ORM

  relevant_files:
    entry_points:
      - path: src/routes/index.ts
        purpose: Route registration
    similar_implementations:
      - path: src/routes/users.ts
        relevance: Similar CRUD endpoint structure
      - path: src/controllers/users.controller.ts
        relevance: Controller pattern to follow
      - path: src/services/users.service.ts
        relevance: Service layer pattern
    test_examples:
      - path: tests/routes/users.test.ts
        pattern: Integration tests with supertest

  conventions_noted:
    naming: "camelCase for variables, PascalCase for classes"
    file_structure: "Feature-based: routes/, controllers/, services/"
    error_handling: "Custom AppError class with HTTP status codes"
    testing: "Jest with supertest, one test file per route file"

  dependencies:
    internal:
      - "src/middleware/auth.ts (authentication)"
      - "src/utils/validators.ts (input validation)"
    external:
      - name: "express"
        version: "^4.18.0"
        purpose: "Web framework"
      - name: "prisma"
        version: "^5.0.0"
        purpose: "Database ORM"

  gaps_in_understanding:
    - "Unclear if preferences should be separate table or JSON column in users table"

  confidence: 0.75
  evidence:
    - "Read: src/routes/users.ts"
    - "Read: src/controllers/users.controller.ts"
    - "Read: tests/routes/users.test.ts"
    - "Searched: 'preferences' in codebase - no existing implementation"

Next Step: Ask user about database schema preference, then proceed to writing-plans skill.

Agent Skills: Context Gathering Skill

Install this agent skill to your local

Skill Files