Technical Context Discovery

Technical Context Discovery

This skill provides a systematic approach for understanding a project's technical context before making any code changes. It ensures consistency with existing patterns and prevents introducing conflicting conventions.

When to Use

• Before implementing any feature or fix
• Before writing tests (unit, integration, E2E)
• Before making architectural decisions that affect existing code
• When onboarding to a new area of the codebase

Technical Context Discovery Process

Use the checklist below and track your progress:

Discovery progress:
- [ ] Step 1: Check project instruction files
- [ ] Step 2: Analyze existing codebase patterns
- [ ] Step 3: Consult external documentation (if needed)
- [ ] Step 4: Apply the implementation rule

Step 1: Check Project Instruction Files

ALWAYS check first for existing project instructions in the repository:

• Search for AGENTS.md — check .codex/AGENTS.md first (primary location in bootstrapped projects), then repo root as fallback.
• If AGENTS.md contains a Skill Routing table, also read the skills/routing/*.md branch files (relative to AGENTS.md's directory) to understand the full routing tree.
• Search for *.instructions.md files in relevant directories (e.g., src/, tests/, e2e/, backend/, feature-specific folders).
• Search for Codex-related project guidance folders or files if present.

If instructions files exist, they are the primary source of truth for:

• Coding standards and conventions
• Architecture patterns and project structure
• Technology stack specifics and version requirements
• Testing strategies and patterns
• Naming conventions and file organization
• Locator strategies (for E2E tests)
• Test data management approaches
• Environment configuration

Step 2: Analyze Existing Codebase Patterns

If no project instructions are found, or if they don't cover specific aspects, analyze the existing codebase to understand and replicate established patterns:

• Architecture patterns: Examine folder structure, layering (controllers, services, repositories), and module organization.
• Code style: Analyze existing files for naming conventions, formatting, and idioms used.
• Error handling: Look at how exceptions are caught, logged, and returned to clients.
• Validation patterns: Check how input validation is implemented (decorators, middleware, manual checks).
• Testing patterns: Review existing tests to understand structure, mocking strategies, assertion styles, fixtures, and test data management.
• Database patterns: Examine existing migrations, entities/models, and query patterns.
• API patterns: Analyze existing endpoints for response formats, status codes, and documentation style.
• Configuration: Check how environment variables, feature flags, and configuration are managed.

Use search and usages tools to find similar implementations in the codebase and follow the same approach.

Step 3: Consult External Documentation

If neither project instructions nor sufficient existing codebase patterns are available (e.g., new project, greenfield feature, or first implementation of a specific pattern), use external documentation and industry best practices:

• Use available documentation search tools to find official framework and library docs (check project config for exact versions first).
• Apply industry-standard best practices for the technology stack.
• Follow OWASP security guidelines for secure coding practices.
• Apply SOLID principles and clean architecture patterns.
• Use well-established design patterns appropriate for the use case.

IMPORTANT: When using best practices in a greenfield scenario, document your decisions in code comments or README to establish patterns for future development.

Step 4: Apply the Implementation Rule

Based on what you discovered, apply this decision hierarchy:

Critical rule: Never introduce new patterns unless explicitly requested by the user or specified in the implementation plan.