name: retrospect
description: This skill reviews the current chat session and GitHub Copilot instructions to identify user-reported issues that should become new lessons, detect violations of existing instructions, and update instructions accordingly to prevent future mistakes.
tags:
- meta-skill
- close-loop

Retrospect Skill

This skill performs meta-analysis on the current conversation and project instructions to continuously improve code quality and adherence to established patterns.

Purpose

This skill helps maintain and improve the quality of AI-assisted development by:
1. Identifying patterns where user corrections reveal gaps in instructions
2. Detecting violations of existing coding standards and conventions
3. Updating instructions to prevent repeating the same mistakes
4. Creating a feedback loop for continuous improvement

When to Use This Skill

Use this skill when:
- A user points out a recurring mistake or anti-pattern
- Multiple corrections have been made during a session
- You want to ensure coding standards are being followed
- A user explicitly requests instruction review or updates
- After completing a significant feature or fix

Retrospect Process

Phase 1: Session Analysis

Objective: Review the current chat session to identify learning opportunities.

1.1 Collect User Corrections

Scan the conversation history for:
- Direct corrections: "No, you should..." or "That's wrong, the correct way is..."
- Repeated mistakes: Same issue corrected multiple times
- Clarifications: "Actually, we use X instead of Y"
- New requirements: "From now on, always do X when Y"
- Anti-patterns: "Don't do X, prefer Y"

1.2 Identify Instruction Gaps

For each correction, determine:
- Is this covered by existing instructions?
- Is this a new pattern that should be documented?
- Is this specific to this project or a general principle?
- Should this be a new rule, guideline, or example?

1.3 Categorize Lessons

Classify lessons by domain and type:
- Architecture: Design patterns, system organization, separation of concerns
- Process: Workflows, procedures, operational patterns
- Behavioral: Agent decision-making, interaction patterns, role adherence
- Communication: Documentation standards, reporting formats, terminology
- Domain-Specific: Business logic, domain rules, specialized requirements
- Quality: Standards, conventions, validation patterns
- Integration: Cross-system patterns, API usage, external dependencies

Phase 2: Constitution Review

Objective: Verify compliance with existing standards and constitutions.

2.1 Load Current Constitutions

Read all relevant constitution and standards documents:
- AGENTS.md - Agent architecture, behavior patterns, and operational guidelines
- SDD files (Software Design Documents) - System design principles and requirements
- Project-specific constitution files (.github/constitution.md, docs/constitution.md)
- Domain-specific standards and guidelines
- Any .copilot-instructions.md or similar instruction files

Document Discovery Strategy:
1. Search for AGENTS.md in project root and docs folders
2. Search for SDD files (look for patterns: *SDD.md, *design*.md, requirements.md)
3. Search for constitution files in .github/, docs/, or root directory
4. Check for skill-specific constitution documents in skills folders

2.2 Scan for Violations

Review actions and outputs from the session against constitutions:
- Process violations: Not following prescribed workflows or procedures
- Principle violations: Contradicting stated design principles or values
- Standard violations: Deviating from established patterns or conventions
- Requirement violations: Missing mandatory elements or constraints
- Behavioral violations: Acting inconsistently with agent role or responsibilities
- Communication violations: Not following documentation or reporting standards

2.3 Cross-Reference with Corrections

Compare user corrections with existing constitutions:
- Was the constitution rule ignored or misunderstood?
- Was the constitution unclear or ambiguous?
- Does the constitution conflict with other guidelines?
- Is the constitution outdated or incorrect?
- Was the violation due to missing context or incomplete information?

Phase 3: Constitution Update

Objective: Formalize lessons learned into actionable constitutions.

Update Strategy:
1. Identify the appropriate constitution document to update
2. Check if a skill exists for updating that document type
3. If a skill exists, invoke it with the update requirements
4. If no skill exists, perform in-place updates following document conventions

3.1 Draft New Constitution Rules

For each identified gap or violation:

Structure:

## [Category]: [Specific Rule]

**Context**: [When does this apply?]

**Rule**: [What should be done?]

**Rationale**: [Why is this important?]

**Example** (if helpful):
```code
// Bad
[anti-pattern]

// Good
[correct pattern]

Related Instructions: [Link to related rules]

#### 3.2 Update Existing Constitutions

**In-Place Update Process**:

For violations of existing constitution rules:
- Clarify ambiguous language
- Add concrete examples relevant to the domain
- Strengthen weak guidelines (e.g., "should" → "must")
- Add cross-references to related rules
- Add "Common Mistakes" or "Anti-Patterns" sections

**Skill-Based Updates** (if available):

1. **Check for update skills**: Search for skills related to the constitution document
   - `openspec-constitution-guard` for OpenSpec constitutions
   - `agents-constitution-updater` for AGENTS.md
   - Document-specific updater skills

2. **Invoke update skill**: If found, call the skill with:
   - The lesson learned
   - The violation context
   - Proposed update text
   - Rationale for the change

3. **Fallback to direct update**: If no skill exists, update the file directly

#### 3.3 Create New Constitution Entries

For lessons that don't fit existing documents, create or update appropriate constitution files:

**Location Options**:
- `.github/constitution.md` - General project principles
- `AGENTS.md` - Agent-specific behaviors and patterns
- `docs/constitution.md` - Domain-specific guidelines
- Skill-specific constitutions in `skills/[skill-name]/constitution.md`

**Format**:
```markdown
# Project Constitution

This document captures project-specific principles and lessons learned.

## [Principle Name]

**Date Added**: YYYY-MM-DD
**Origin**: [What situation led to this principle?]

**Principle**: [Clear statement of the rule]

**Application**: [How to apply this in practice]

**Examples**: [Concrete examples]

Phase 4: Validation

Objective: Ensure updates are effective and non-disruptive.

4.1 Review Changes

• Ensure new instructions don't contradict existing ones
• Verify examples are accurate and compilable
• Check that rationale is clear and convincing
• Confirm changes are actionable (specific, measurable)

4.2 Test Instructions

• Review recent code against updated instructions
• Verify instructions would have prevented the mistake
• Check for unintended consequences or side effects

4.3 Summarize Changes

Provide a summary:

## Retrospect Summary

### Lessons Learned
1. [Lesson 1]: [What was learned and why]
2. [Lesson 2]: [What was learned and why]

### Instructions Updated
- **File**: [filename]
  - **Section**: [section name]
  - **Change**: [what was changed]
  - **Reason**: [why it was changed]

### New Violations Detected
1. [Violation 1]: [Description and location]
2. [Violation 2]: [Description and location]

### Recommendations
- [Action item 1]
- [Action item 2]

Output Format

The retrospect process should produce:

1. Retrospect Report (printed to console):
2. Summary of lessons learned
3. List of instruction violations

4. Recommendations for improvement

5. Updated Constitution Files:

6. Modified AGENTS.md with updated agent behaviors and principles
7. Updated SDD files with refined design requirements
8. Modified constitution.md files with clarifications and new rules

9. Skill-specific constitution updates

10. Action Items:

11. Processes that need refinement
12. Behaviors that need adjustment
13. Documentation that needs updating
14. Skills that need to be created or modified

Best Practices

Constitutions

1. Be Specific: "Validate inputs" → "All agent operations MUST validate input structure and constraints before any processing or state chang
2. Be Specific: "Use Pydantic models" → "Use Pydantic models instead of dict[str, Any] for all API request/response bodies"
3. Explain Why: Include rationale so the principle is understood, not just memorized
4. Provide Examples: Show both the wrong way and the right way
5. Make it Actionable: Instructions should be clear enough to follow without interpretation
6. Prioritize: Use "must", "should", "prefer" to indicate priority level

Avoiding Over-Prescription

• Don't create rules for one-off situations
• Focus on patterns that repeat across multiple instances
• Leave room for judgment and context-specific decisions
• Balance between guidance and flexibility

Maintaining Consistency

• Use consistent terminology across all instruction files
• Cross-reference related instructions
• Organize instructions hierarchically (general → specific)
• Keep a single source of truth for each concept

Implementation Guidelines

When Running Retrospect

1. Start with analysis: Don't jump to solutions
2. Be thorough: Review entire conversation history
3. Stay objective: Look for patterns, not just recent issues
4. Think long-term: Will this instruction scale as the project grows?
5. Validate changes: Test that new instructions would prevent the issue

After Retrospect

1. Apply updates immediately: Update instruction files right away
2. Communicate changes: Summarize what changed and why
3. Verify effectiveness: Check if similar mistakes are prevented
4. Iterate: Retrospect is continuous, not one-time

Example Scenarios

Scenario 1: Workflow Process Violation

User Correction: "Don't skip the validation step - always validate inputs before processing"

Analysis:
- Violation of established workflow in AGENTS.md or SDD
- Skipped mandatory process step

Constitution Update (AGENTS.md):

### Input Validation Protocol

**Context**: All agent operations that accept external inputs

**Rule**: Input validation MUST occur before any processing or state changes.

**Rationale**: Prevents cascading errors and ensures data integrity throughout the system.

**Process**:
1. Receive input
2. Validate structure and constraints
3. Transform to internal representation
4. Process validated data

**Anti-Pattern**: Processing data before validation

**Related**: See "Error Handling Standards" and "State Management"

Scenario 2: Agent Role Violation

User Correction: "This agent shouldn't be making decisions about deployment - that's the DevOps agent's responsibility"

Analysis:
- Violation of agent role boundaries defined in AGENTS.md
- Overstepping defined responsibilities

Constitution Update (AGENTS.md):

### Agent Responsibility Boundaries

**Context**: Multi-agent system with defined roles

**Rule**: Each agent MUST operate only within its defined domain. Cross-domain decisions require delegation to the appropriate agent.

**[AgentName] Responsibilities**:
- [Primary responsibility 1]
- [Primary responsibility 2]

**NOT Responsible For**:
- Deployment decisions → DevOps Agent
- Security policies → Security Agent
- Resource allocation → Resource Manager Agent

**Delegation Protocol**: When encountering a task outside your domain:
1. Identify the appropriate agent
2. Format the delegation request
3. Hand off with full context
4. Wait for response or acknowledgment

**Rationale**: Maintains clear separation of concerns and prevents conflicting decisions.

References

• Agent architecture: AGENTS.md
• System design: SDD files in spec/ or docs/
• Constitution documents: .github/constitution.md, docs/constitution.md
• Update skills: skills/openspec-constitution-guard/, skills/*/constitution.md
• Workflow documentation: Project-specific process documents

Continuous Improvement

This skill itself should evolve:
- Add new analysis patterns as they emerge
- Refine the instruction update format
- Improve violation detection accuracy
- Enhance the categorization of lessons

The meta-goal is to make AI-assisted development increasingly accurate and aligned with project standards over time.