reflect-on-changes

Reflect on Changes

Use this skill after meaningful code changes, review passes, workflow updates, or bug-fix loops.

The goal is to turn local knowledge into durable repository knowledge.

Core Outcomes

1. Update the docs, commands, or skills that became stale because of the change.
2. Identify repeatable problems that should be enforced mechanically instead of re-reviewed manually.
3. Either implement the enforcement immediately when it is low-risk and clearly scoped, or record a concrete follow-up.

Workflow

1. Gather the learning scope.
   • Inspect the current diff against main plus any untracked files that matter.
   • Read any rolling review artifacts if present.
   • Read touched docs, commands, skills, configs, and validation scripts before concluding they are up to date.
2. Determine what repository knowledge changed.
   • conventions
   • command behavior
   • skill behavior
   • validation workflow
   • developer expectations
3. Update the source of truth directly.
   • Prefer updating the most specific doc first, then update summaries.
   • Keep related docs and affected command/skill files in sync.
4. Mine repeated problems from the change and review history.
   • Look for issues that appeared more than once in the same task or across related files.
   • Treat "we had to fix this manually again" as a strong signal for mechanical enforcement.
5. Choose the right enforcement layer.
   • ESLint: AST-shaped TS/JS rules and import/code-organization invariants.
   • Nx/module-boundary config: project graph and tag dependency rules.
   • Semgrep: security patterns and broader code-shape checks.
   • Knip: dead code, unused exports, dependency drift.
   • Custom script/CI check: docs freshness, repo metadata, or non-AST structural validation.
   • Docs only: judgment-heavy guidance that should not be mechanized yet.
6. Act on the best candidates.
   • Implement low-risk, well-understood enforcement immediately when it fits the current task.
   • Otherwise add a concrete follow-up entry with:
     • the repeatable problem
     • recommended enforcement layer
     • why it is worth mechanizing
     • any expected false-positive risk or rollout caveat
7. Summarize what was learned.
   • docs updated
   • commands/skills updated
   • enforcement added
   • follow-up lint-rule or validation candidates deferred