| name | reflect |
| description | Review CLAUDE.md, auto-memory, WIP docs, and skills against recent development activity for accuracy, compaction, drift, and cross-file consistency. |
Reflect on Application Context
Perform a comprehensive review of the project's context files — CLAUDE.md, auto-memory, WIP documents, and skill definitions — against recent development activity. The goal is to keep these files accurate, concise, and aligned with how the codebase actually works today.
Read rubric.md (in this skill directory) before analyzing. It defines what makes a CLAUDE.md entry worth adding or keeping, and helps distinguish high-value findings from noise.
Step 1: Gather Context
- Read
CLAUDE.md at the project root.
- Read
rubric.md in this skill directory.
- Read all auto-memory files in the
.claude/projects/ memory directory (if any exist).
- Read all
.claude/wip/*.md files (if any exist).
- Read all
.claude/skills/*/SKILL.md and companion files (e.g., patterns.md).
- Run
git log --oneline -30 to see recent commits.
- For commits that match the signals below, run
git show --stat <hash> to understand what files were touched.
Signals that indicate context-relevant changes
Look for these specific patterns in commit subjects and touched files:
| Signal | What it means |
|---|
New *Cascade.cfc, *Access.cfc, *Service.cfc | New entity lifecycle patterns |
Commits touching cfmlx.cfm | New or changed global utility functions |
Commits touching _shared/tag/ | New shared tags (may need entry-point imports) |
Commits modifying CLAUDE.md | Recent context updates — check for completeness |
| Merge commits | Completed feature branches — check for stale WIP docs |
| Commit messages with "pattern", "convention", "refactor", "restructure" | Architecture decisions |
New directories under cfml/app/client/ | New subsystem routes |
New .sql files in cfml/app/db/ | Database conventions |
New *Sanitizer.cfc files | HTML sanitization patterns |
Commits touching UI.cfc | New UI helper methods |
Step 2: Scan for Undocumented Patterns
Use structured searches — Grep and Glob first, Read to confirm — rather than browsing.
Entity component inventory
Glob for *Model.cfc, *Gateway.cfc, *Validation.cfc, *Service.cfc, *Access.cfc, *Cascade.cfc, *Sanitizer.cfc under cfml/app/core/lib/model/ and cfml/app/core/lib/service/. Cross-reference with what CLAUDE.md documents:
- Are there new entity types not mentioned in CLAUDE.md?
- Have new component types (e.g.,
*Sanitizer.cfc) become a recurring convention worth documenting?
- Have entities gained or lost Service/Access/Cascade components since CLAUDE.md was last updated?
Shared component inventory
Glob for cfml/app/client/_shared/tag/*.cfm. Check whether recently added tags need:
- Mention in CLAUDE.md
- Explicit import statements in subsystem entry points (e.g.,
member.js, share.js)
Utility function inventory
Read cfml/app/core/cfmlx.cfm and compare the actual function list against the "Global Extensions" section in CLAUDE.md. Flag additions, removals, and category mismatches.
UI helper inventory
Grep for public methods in UI.cfc. Compare against any UI helper lists in CLAUDE.md or in the security-review skill's safe-pattern list. New helpers that aren't listed will cause false positives in security reviews.
Step 3: Check for Drift
Verify specific CLAUDE.md claims against the actual codebase. Apply the severity labels below — they determine finding priority in the final report.
| Check | Severity | How to verify |
|---|
| Key Directories tree | HIGH | ls the actual directories and compare |
cfmlx.cfm function list | HIGH | Read the file, diff against documented list |
| Client subsystem names | MEDIUM | Glob cfml/app/client/*/ |
| Build commands | MEDIUM | Read package.json and docker-compose.yml |
| Entity pattern description | MEDIUM | Spot-check 2-3 entity directories for Model/Gateway/Validation |
| Form field patterns | LOW | Spot-check 2-3 .view.cfm files for ui.nextFieldId() usage |
| Code formatting examples | LOW | Spot-check 2-3 .cfc files for section comment style |
Severity definitions:
- HIGH — Will actively mislead Claude into generating incorrect code or structure
- MEDIUM — Could cause confusion or suboptimal output, but won't break things
- LOW — Minor inaccuracy or style drift, unlikely to cause real problems
Step 4: Analyze for Compaction
Review CLAUDE.md for opportunities to tighten without losing information. Apply the rubric from rubric.md to assess whether each section earns its space.
- Redundancy: Are any concepts explained in multiple sections? (Common between "Architecture" and code formatting sections.)
- Verbosity: Could prose be replaced with a bullet or shorter phrasing?
- Stale content: Do any sections describe something that no longer matches reality? (Cross-reference with Step 3.)
- Code examples: Are any examples longer than needed to illustrate the point? Could an example be trimmed by a few lines and still convey the pattern?
- Section organization: Could sections be merged or reordered for better flow?
- Low-value entries: Do any sections document patterns that are single-use, obvious, or unstable? (Apply the rubric's "Three File Test.")
Step 5: Reconcile Auto-Memory
If auto-memory files exist (in .claude/projects/*/memory/), evaluate each entry:
| Action | Criteria |
|---|
| Promote | Pattern confirmed across multiple interactions, not yet in CLAUDE.md. Recommend adding to CLAUDE.md and removing from auto-memory. |
| Deduplicate | Entry already covered by CLAUDE.md. Recommend removing from auto-memory. |
| Contradict | Entry conflicts with CLAUDE.md. Flag for resolution — which source is correct? |
| Keep | Valid but too narrow or session-specific for CLAUDE.md. Leave in auto-memory. |
If MEMORY.md says "No additional notes beyond what's documented in the project's CLAUDE.md" and no other memory files exist, note this step as clean and move on.
Step 6: Review WIP Documents
For each file in .claude/wip/:
- Read the document to understand what feature it describes.
- Search git history for evidence the feature has shipped — look for merge commits, related file additions, or keywords from the PRD.
- Classify and recommend:
| Status | Evidence | Recommendation |
|---|
| Shipped | Merge commit exists, feature files are in the codebase | Flag for removal. Note which commits completed the feature. |
| In progress | Feature branch exists or partial implementation found | Check whether the PRD still reflects current plans (it may have drifted during implementation). |
| Abandoned | No recent activity, no related branch | Flag for removal if the feature appears shelved. |
If .claude/wip/ doesn't exist or is empty, note this step as clean and move on.
Step 7: Cross-Skill Consistency
Check whether recent CLAUDE.md or codebase changes need to be reflected in skill definitions.
Security-review safe patterns
The security-review skill's patterns.md lists safe patterns that should NOT be flagged (e.g., ui.* helpers, encoding functions, pre-sanitized *Html fields). Check for:
- New
ui.* methods in UI.cfc not listed in the security-review's safe-pattern table
- New encoding functions in
cfmlx.cfm not listed as safe
- New
*Html fields (from new Sanitizer components) not listed as safe pre-sanitized output
- New subsystems or directories that should be in the security-review's scan scope
Skill-to-CLAUDE.md references
If a skill references a CLAUDE.md concept by name (e.g., "the maybe pattern", "the cascade delete pattern"), verify that CLAUDE.md still describes it with that name and meaning.
Skill scope alignment
If new entity types, subsystems, or component categories were added, check whether skills that scan specific directories need their scope expanded.
Step 8: Present Findings
Organize findings by severity (HIGH first), then by category.
Report format
## Summary
HIGH: [count]
MEDIUM: [count]
LOW: [count]
CLEAN: [count of steps with no findings]
Findings
For each finding:
### [Category] — [SEVERITY]
**What**: The specific change recommended.
**Why**: The reasoning (drift, compaction, missing pattern, cross-skill gap, etc.).
**Where**: The file and section affected.
Group related findings under the same category header when they affect the same file or section.
Rules
- Do NOT make any edits automatically. Present findings and let the user decide which changes to make.
- The user may want to discuss, adjust, or reject individual suggestions before anything is changed.
- Keep the tone collaborative — this is a maintenance review, not a critique.
