agentleFS
whoaskedssselerywhoaskedssselery/claude-workspace/skills/core/health-review/SKILL.md

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.

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
  1. Distinctive:

    Only report findings supported by evidence in the codebase.

    line 30
  2. Distinctive:

    If something is uncertain, present it as a question or hypothesis rather than a conclusion.

    line 32
  3. Distinctive:

    Avoid suggesting changes solely because another approach exists.

    line 40
  4. Distinctive:

    Do not recommend refactoring working code without meaningful benefit.

    line 48
  5. Distinctive:

    Prefer consistency over stylistic perfection.

    line 50
  6. Distinctive:

    If the language has a type system, review:

    line 109
  7. Very specific:

    use of escape hatches (any and equivalents).

    line 111
  8. Distinctive:

    Look for architectural drift rather than isolated violations.

    line 133
  9. Distinctive:

    Ask 2–5 questions that encourage architectural thinking.

    line 251
  10. Distinctive:

    Never rewrite entire features.

    line 285
  11. Distinctive:

    Prefer questions over solutions.

    line 287
  12. Distinctive:

    If project-specific tooling (such as Impeccable) is available, recommend appropriate commands where helpful.

    line 290

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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, /review or /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 (any and 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.