cyberelf/retrospect

Retrospect Skill

This skill performs meta-analysis on the current conversation and project instructions to continuously improve code and process 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):

   • Summary of lessons learned
   • List of instruction violations
   • Recommendations for improvement

2. Updated Constitution Files:

   • Modified AGENTS.md with updated agent behaviors and principles
   • Updated SDD files with refined design requirements
   • Modified constitution.md files with clarifications and new rules
   • Skill-specific constitution updates

3. Action Items:

   • Processes that need refinement
   • Behaviors that need adjustment
   • Documentation that needs updating
   • 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.