imvanzen/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 Cursor rules and 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 Cursor Rules and Project Instruction Files

ALWAYS check first for existing Cursor rules and project instructions:

• Search for .cursor/rules/*.md at the repository root (project-wide rules).
• If present, review any agent instruction files at the repository root (for example, AGENTS.md). AGENTS.md is optional; the repo may not have it yet.
• Search for *.instructions.md files in relevant directories (e.g., src/, tests/, e2e/, backend/, feature-specific folders).
• Review the .cursor/ directory for rules, skills, and agent configurations.

If Cursor rules or instruction 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 Cursor rules or instruction files 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 Cursor rules/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 context7 tool to search for official documentation of the framework/library being used (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:

| Context Available | Action | |---|---| | Cursor rules or instruction files exist | Follow them strictly. Rules and instructions take precedence over general best practices. | | No rules/instructions, but codebase has patterns | Mirror existing patterns exactly. Consistency with existing code > theoretical best practices. | | No rules/instructions, no existing patterns | Apply documentation-based best practices and industry standards. Document decisions for future reference. |

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