retro-copilot

Retro Copilot

Extract reusable insights from incidents and conversations,~/.copilot and create change proposals to reflect them in the instructions / skills / agents / hooks / related config under

When to Use

• Use: after resolving a bug / when a recurrence occurs / when a review finds a design gap in the personal assets under .copilot Use: after resolving a bug / when a recurrence occurs / when a review finds a design gap in the personal assets under
• Use: ~/.copilot/copilot-instructions.md、~/.copilot/instructions/**、~/.copilot/skills/**、~/.copilot/agents/**、~/.copilot/hooks/** when there is operational knowledge that should be reflected in
• Do not use: only minor fixes such as typos / only environment-specific problems
• Do not use: content specific to a workspace / repository (pass it to the retro workflow for workspace/repository assets)
• Do not use: content of VS Code User Data (pass it to the retro workflow for VS Code User Data assets)
• Do not use: private skills repository's .github/skills/**(pass it to the retro workflow for private skills repositories)

Core Rules

• memory is not used as a reflection target
  • /memories/**, user memory, session memory, and repo memory are not targeted
• The default mode is safe-auto。.copilot If the scope is clear, it passes the Safety & Scope Gate, and only small- to medium-scale integration or updates to existing assets are required, you may execute through reflection without confirmation
• review-only / 確認だけ / dry-run / プレビュー Only when is explicitly specified, stop at presenting the change proposal
• Confirm only unclear scope, new privileges/destinations/visibility/defaults, destructive deletion or uncertain sensitive data; otherwise use safe-auto without reapproval. Read-only and holds take precedence.
• Match committed implementation, not local drafts; defer unsupported operations rather than inventing capabilities.
• List up to three scoped read-only follow-ups: authoring/private-push/distribution gaps. Honor holds and visibility; never widen actions or audits from a suggestion.
• If the content belongs to another scope, do not edit it yourself; hand it off

Workflow

Context -> Extract -> Safety & Scope Gate -> Decide Action & Target -> Validate & Output

Phase 1: Context Collection

• Input (at least one required)
  • Error logs, diffs/commits, conversation history, terminal history, existing .copilot assets
• Default reflection scope
  • ~/.copilot Prioritize personal global customization assets under
  • Knowledge that should be reflected in a workspace / repository or VS Code User Data is not handled by this skill; propose a handoff. For workspace handoff, specify the active workspace provided by the host, and do not create or propose a new external project folder
• Terminal perspective
  • Exit Code != 0
  • Ctrl+C (interrupt)
  • Repeating the same command
  • Long-running execution
• Gate: if there is no input, request additional input and stop

Phase 2: Extract Learnings

• Category
  • Design principles (SRP/SSOT/idempotency)
  • Workflow
  • Prompt design
  • Context design
  • Error pattern
• For each item, create Learning / Evidence / Impact For each item, create
• Gate: stop if there are no actionable insights

Phase 2.5: Safety & Scope Gate

• Information that must not be reflected or needs abstraction
  • Secrets, credentials, API keys, connection strings
  • Personal information, customer information, personal account values
  • Local absolute paths, device-specific values, temporary directories
  • Conversation text or log fragments unsuitable for external sharing
• No Memory Targets Gate
  • /memories/**, user memory, session memory, and repo memory are not used as reflection targets
  • Requests that need to be kept in memory are not executed by this skill; explicitly confirm them as a separate task
• Scope Gate
  • ~/.copilot Check whether the content should be placed in assets under
  • If the content should be placed in a workspace / repository or VS Code User Data, do not reflect it in this skill; propose a handoff
• Gate (all required)
  • Knowledge to be persisted is abstracted into reusable rules
  • Evidence is minimal and contains no sensitive information
  • ~/.copilot Confirmed that it is content that should be placed under
  • Self-Contained: The added content does not depend on hard references to other files or workspace-specific values, and~/.copilot functions standalone (also respects tool constraints: e.g. since Copilot CLI cannot use prompts, choose SKILL as the primitive)
  • Passed the No Memory Targets Gate

Refactor Context Rules

• Follow SSOT. Consolidate duplicate definitions
• Prioritize integration into existing files over creating new files. Add 1 section / 1 rule / navigation to a catch-all existing file, and allow a new file only when it does not fit an existing role and Target Rationale can explain the necessity
• For small files of 50 lines or fewer, leave unchanged or make minimal diffs unless there is clear value
• Compress redundant explanations, but do not remove source URLs, non-obvious procedures, or operational meta-comments
• Target Rationale In this case, always explain "why existing integration rather than new creation"

Phase 3: Decide Action & Target

• Priority: Impact x Recurrence (P1/P2/P3)
• Destination
  • Common principles → ~/.copilot/copilot-instructions.md
  • domain instructions → ~/.copilot/instructions/**/*.instructions.md
  • skills → ~/.copilot/skills/**/SKILL.md
  • agents → ~/.copilot/agents/**/*.agent.md
  • hooks → ~/.copilot/hooks/**/*.json
  • related config → then limit to
    • ~/.copilot/config.json
    • ~/.copilot/settings.json
    • ~/.copilot/permissions-config.json
    • ~/.copilot/mcp-config.json
    • ~/.copilot/mcp-oauth-config/**(only those directly consistent with the customization)
• Judgment of single vs multiple destinations
  • Principle: Integrate into the single most specific file
  • Exception (multiple destinations allowed): Cross-cutting principles that multiple files should independently own (e.g. tool-platform constraints, Self-Contained gate, cwd discipline) may be added as one line to all applicable files. Each copy should function standalone as an independent SSOT, without depending on hard references to other files. Do not copy the same long block; put only one line of judgment in each file
• Prohibited destinations
  • workspace / repository の AGENTS.md、.github/**、workspace docs
  • VS Code User Data の *.prompt.md / *.instructions.md / *.agent.md
  • /memories/**、user memory、session memory、repo memory
  • command-history-state.json、session-store.db、vscode.session.metadata.cache.json
  • session-state/**、logs/**、pkg/**、crash-context/**、restart/** runtime artifacts and caches such as
• When the destination file does not exist:
  • It may be newly created with safe-auto. However, if it can be integrated into existing assets, prioritize integration
  • If the directory is also absent, show the planned path and the reason
  • Only when unsure about scope or public availability, proceed to the duplicate/contradiction check after user approval

Decision Rules

• Choose instructions in principle, skills for task procedures, agents for role separation, and hooks for deterministic automation, based on their respective domains
• Handoff destination: Knowledge for workspace / repository, VS Code User Data, and private skills repository is passed to the retro workflow for that scope (not edited in this skill)
• Apply with minimal diffs

Output Requirements

• ## Learnings
• ## Changes
• ## Target Rationale
• ## Review Checkpoint

## Review Checkpoint must at minimum include the following:

• safe-auto executed or user approval obtained when gated
• Copilot scope confirmed
• No duplicate rules verified
• Target files are writable
• Safety & Scope Gate passed
• No memory target selected