health-review
Skill0 starsChanged 4 months agoMITView on GitHub
Periodic project health audit, for any stack. Reviews architecture, maintainability, design consistency, type safety, recurring issues and learning opportunities. Provides evidence-based, actionable feedback while respecting learning-guard where it applies.
In this repository8 other files it gives its agents.
- assignment-modeSkill
- codegraphSkill
- commit-disciplineSkill
- debug-modeSkill
- learning-guardSkill
- teacherSkill
- assignment-defendSkill
- spikeSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 11 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Only report findings supported by evidence in the codebase.
- Distinctive: line 32
If something is uncertain, present it as a question or hypothesis rather than a conclusion.
- Distinctive: line 40
Avoid suggesting changes solely because another approach exists.
- Distinctive: line 48
Do not recommend refactoring working code without meaningful benefit.
- Distinctive: line 50
Prefer consistency over stylistic perfection.
- Distinctive: line 109
If the language has a type system, review:
- Very specific: line 111
use of escape hatches (any and equivalents).
- Distinctive: line 133
Look for architectural drift rather than isolated violations.
- Distinctive: line 251
Ask 2–5 questions that encourage architectural thinking.
- Distinctive: line 285
Never rewrite entire features.
- Distinctive: line 287
Prefer questions over solutions.
- Distinctive: line 290
If project-specific tooling (such as Impeccable) is available, recommend appropriate commands where helpful.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Health Review
Purpose
Perform a structured, evidence-based health check of the current project.
Identify:
- real problems;
- architectural drift;
- recurring mistakes;
- maintainability risks;
- learning opportunities.
Preserve good decisions.
Guide the human toward improvements without taking over implementation.
Review Philosophy
Evidence First
Only report findings supported by evidence in the codebase.
If something is uncertain, present it as a question or hypothesis rather than a conclusion.
Context Over Rules
Evaluate decisions within the project's context.
Avoid suggesting changes solely because another approach exists.
A pattern that is usually discouraged may still be the correct choice for this project.
Preserve Stability
Do not recommend refactoring working code without meaningful benefit.
Prefer consistency over stylistic perfection.
Detect architectural drift and regressions before isolated imperfections.
Look for Patterns
Repeated issues are more important than isolated mistakes.
Focus on trends that indicate:
- missing understanding;
- inconsistent habits;
- architectural decay.
When to Run
Run when:
- the user requests
/health,/reviewor/review-project; - roughly every 15–25 commits;
- before major refactors;
- the project begins feeling inconsistent or difficult to maintain.
Review Areas
1. UI / UX
Review:
- visual consistency;
- spacing;
- typography;
- colors;
- accessibility;
- hover, focus, loading and empty states;
- consistency with the design system.
Identify visual regressions rather than personal preferences.
2. Responsive Design
Check whether:
- mobile-first principles remain consistent;
- layouts scale correctly;
- important breakpoints behave as expected.
3. Type Safety
If the language has a type system, review:
- use of escape hatches (
anyand equivalents); - overly broad types;
- unnecessary assertions;
- missing narrowing;
- type inference opportunities;
- validation at boundaries where appropriate.
Assume strict use of the type system.
4. Architecture
Review, in terms of whatever architectural pattern the project actually follows:
- layer/module boundaries;
- dependency direction;
- import rules;
- separation of concerns;
- layer responsibilities;
- cohesion and coupling.
Look for architectural drift rather than isolated violations.
5. State Management
Review boundaries between:
- server state;
- client state;
- local UI state.
Evaluate, in terms of whatever the project's actual data-fetching and state libraries are:
- data-fetching/caching layer usage;
- global client-state store usage;
- query invalidation;
- query keys;
- unnecessary global state;
- form architecture and validation integration.
6. Maintainability
Review:
- duplication;
- dead code;
- unused exports;
- commented code;
- component complexity;
- naming consistency;
- folder organization.
Recommend splitting code only when complexity meaningfully affects readability or maintenance.
7. Learning Signals
Identify recurring learning patterns.
Differentiate between:
- accidental mistakes;
- knowledge gaps;
- inconsistent habits.
Recommend concepts to revisit rather than only pointing out errors.
Report Format
Overall Summary
Provide:
- overall project status;
- main strengths;
- highest-priority risks.
Health Scores
Estimate (0–10):
- Architecture
- Type Safety
- UI / UX
- Maintainability
- Learning Progress
Also provide an overall score.
Scores should indicate trends rather than absolute quality.
Findings
For each significant finding include:
- evidence (files, components or locations);
- severity;
- explanation;
- recommended direction.
Severity levels:
- Critical
- High
- Medium
- Low
- Nice to Have
Action Plan
Fix Now
High-impact issues.
Fix Soon
Important improvements.
Watch Later
Minor improvements or stylistic cleanup.
Reflection Questions
Ask 2–5 questions that encourage architectural thinking.
Examples:
- Why is this state global?
- Could this dependency move to a lower layer?
- Is this component responsible for more than one concern?
- What trade-off did you optimize for?
Questions should encourage reasoning rather than test memory.
Suggested Learning Topic
Recommend one concept whose deeper understanding would provide the greatest improvement.
Explain why this topic is the highest leverage.
Positive Observations
Highlight good engineering decisions.
Reinforce successful patterns.
Explain why they are good so the human is encouraged to repeat them.
Rules
- Respect learning-guard at all times.
- Never rewrite entire features.
- Small snippets (1–5 lines) are acceptable only to illustrate a recommendation.
- Prefer questions over solutions.
- Be honest, specific and constructive.
- Preserve existing good patterns.
- If project-specific tooling (such as Impeccable) is available, recommend appropriate commands where helpful.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

