tsh-technical-context-discovering

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 0: Check plan file for persisted context
- [ ] Step 1: Check Copilot instruction files
- [ ] Step 2: Analyze existing codebase patterns
- [ ] Step 3: Consult external documentation (if needed)
- [ ] Step 4: Apply the implementation rule

Step 0: Check Plan File for Persisted Context

ALWAYS check first whether a plan file (*.plan.md) exists for the current task and contains a "Technical Context" section.

If a "Technical Context" section exists and is populated:

• Use it as-is — do not re-discover conventions, patterns, or standards that are already documented there.
• Skip Steps 1-2 entirely. Proceed directly to Step 4 (Apply the implementation rule) using the persisted context.
• Only perform targeted discovery (Steps 1-2) for aspects not covered by the persisted context.

If no plan file exists, or the "Technical Context" section is missing/empty:

• Proceed with Steps 1-4 as normal.

Step 1: Check Copilot Instruction Files

ALWAYS check first for existing Copilot instructions in the project:

• Search for .github/copilot-instructions.md at the repository root.
• Search for *.instructions.md files in relevant directories (e.g., src/, tests/, e2e/, backend/, feature-specific folders).
• Search for .copilot/ directory with configuration files.

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 Copilot 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 Copilot 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:

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