Generate Custom Instructions From Codebase

Generate custom instructions from codebase

Compare two project states, extract real before/after transformation patterns, and write .github/copilot-migration-instructions.md so GitHub Copilot can preserve the migration's conventions in future edits.

When to invoke

• "Generate Copilot instructions from this migration branch."
• "Compare these commits and document the new conventions."
• "Create migration instructions for our framework upgrade."
• "Teach GitHub Copilot to avoid obsolete patterns after this refactor."
• "Build a before/after API correspondence guide from the codebase."

Inputs

Use $ARGUMENTS for the migration configuration. Required values are MIGRATION_TYPE, SOURCE_REFERENCE, and TARGET_REFERENCE; optional values are ANALYSIS_SCOPE, CHANGE_FOCUS, AUTOMATION_LEVEL, GENERATE_EXAMPLES, and VALIDATION_REQUIRED.

Configuration model

Procedure

1. Resolve SOURCE_REFERENCE and TARGET_REFERENCE to concrete commits, branches, or tags.
2. Compare folder structure and detect moved, renamed, deleted, and added files.
3. Analyze configuration changes, new dependencies, and removed dependencies.
4. Extract code transformation patterns based on MIGRATION_TYPE and CHANGE_FOCUS.
5. Build a before/after correspondence matrix with mandatory transformations, validation-required transformations, API mappings, new patterns, and obsolete patterns.
6. Generate .github/copilot-migration-instructions.md with examples when GENERATE_EXAMPLES=true.
7. Test the instructions against representative changed code, then adjust rules and exceptions.

Migration analysis focus

Instruction sections

Generated file template

# GitHub Copilot Migration Instructions

## Migration Context
- **Type**: <MIGRATION_TYPE>
- **From**: <SOURCE_REFERENCE>
- **To**: <TARGET_REFERENCE>
- **Date**: <GENERATION_DATE>
- **Scope**: <ANALYSIS_SCOPE>

## Automatic Transformation Rules

### 1. Mandatory Transformations
- **Old Pattern**: <OLD_CODE>
- **New Pattern**: <NEW_CODE>
- **Trigger**: <when to detect this pattern>
- **Action**: <transformation to apply automatically>

### 2. Transformations with Validation
- **Detected Pattern**: <description>
- **Suggested Transformation**: <NEW_APPROACH>
- **Required Validation**: <VALIDATION_CRITERIA>
- **Alternatives**: <ALTERNATIVE_OPTIONS>

### 3. API Correspondences
| Old API | New API | Notes | Example |
| --- | --- | --- | --- |
| <OLD_API> | <NEW_API> | <changes> | <CODE_EXAMPLE> |

### 4. New Patterns to Adopt
- **Pattern**: <PATTERN_NAME>
- **Usage**: <WHEN_TO_USE>
- **Implementation**: <HOW_TO_IMPLEMENT>
- **Benefits**: <advantages>

### 5. Obsolete Patterns to Avoid
- **Obsolete Pattern**: <OLD_PATTERN>
- **Why Avoid**: <reasons>
- **Alternative**: <NEW_PATTERN>
- **Migration**: <CONVERSION_STEPS>

## File Type Specific Instructions

### Configuration Files
<CONFIG_TRANSFORMATION_EXAMPLES>

### Main Source Files
<SOURCE_TRANSFORMATION_EXAMPLES>

### Test Files
<TEST_TRANSFORMATION_EXAMPLES>

## Validation and Security

### Automatic Control Points
- <tests, performance metrics, compatibility checks>

### Manual Escalation
- <COMPLEX_CASES_LIST>
- <ARCHITECTURAL_DECISIONS>
- <BUSINESS_IMPACTS>

## Migration Monitoring

### Tracking Metrics
- Percentage of code automatically migrated
- Number of manual validations required
- Error rate of automatic transformations
- Average migration time per file

### Error Reporting
- Feedback patterns to improve rules
- Exceptions to document
- Adjustments to make to instructions

Transformation example format

// BEFORE (<SOURCE_REFERENCE>)
<OLD_CODE_EXAMPLE>

// AFTER (<TARGET_REFERENCE>)
<NEW_CODE_EXAMPLE>

// COPILOT INSTRUCTIONS
When you see this pattern <trigger>, transform it to <NEW_PATTERN> following these steps: <steps>.

Typical use cases

Criteria

• Instructions are based on actual diffs, not generic migration advice.
• Automatic rules are only used when the old pattern has a reliable trigger and deterministic replacement.
• Validation-required transformations name concrete tests, compatibility checks, or manual review criteria.
• API correspondence entries preserve old/new names and examples from the codebase.
• Obsolete patterns explain why they are wrong and what to use instead.
• Security and business-impact changes are escalated for human review.

Migration placeholders

Preserve placeholders used by generated migration instructions: ADVANTAGES, CHANGES, DESCRIPTION, REASONS, STEPS, TRIGGER, and cross-version.

Output template

## Copilot migration instructions result

**Status:** generated | needs validation | blocked
**Output file:** `.github/copilot-migration-instructions.md`
**Migration:** `<MIGRATION_TYPE>` from `<SOURCE_REFERENCE>` to `<TARGET_REFERENCE>`

### Patterns extracted
| Category | Count | Examples |
| --- | --- | --- |
| Mandatory transformations | <count> | <summary> |
| Transformations with validation | <count> | <summary> |
| API correspondences | <count> | <summary> |
| New patterns | <count> | <summary> |
| Obsolete patterns | <count> | <summary> |

### Validation
- Test application on sample code: pass | fail | not run
- Exceptions documented: pass | fail
- Manual escalations listed: pass | fail

Quality gate

• MIGRATION_TYPE, SOURCE_REFERENCE, TARGET_REFERENCE, ANALYSIS_SCOPE, CHANGE_FOCUS, AUTOMATION_LEVEL, GENERATE_EXAMPLES, and VALIDATION_REQUIRED are recorded.
• .github/copilot-migration-instructions.md is generated with migration context and transformation rules.
• API mappings retain OLD_API, NEW_API, and CODE_EXAMPLE when API changes are in scope.
• Examples include OLD_CODE_EXAMPLE and NEW_CODE_EXAMPLE when requested.
• COMPLEX_CASES_LIST, ARCHITECTURAL_DECISIONS, and BUSINESS_IMPACTS are escalated instead of automated.
• Validation and monitoring guidance is concrete enough for future GitHub Copilot edits.