agentleFS
imbue-aiimbue-ai/sculptor/.claude/skills/update-review-rules/SKILL.md

update-review-rules

Skill246 starsChanged 5 months agoMITView on GitHub

Add a new issue type to one of Sculptor's review-rule docs. Use when you've encountered a class of bugs, anti-patterns, or flaky test patterns that should be caught in future reviews.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 3 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add a new issue type to one of Sculptor's review-rule docs to prevent a class of issues from recurring.

    line 11
  2. Distinctive:

    Read all the review docs listed above to understand the existing rules, their format, and their naming conventions.

    line 30
  3. Very specific:

    If the rule is about Playwright tests, integration test patterns, or test isolation/structure → integration_tests.md.

    line 32
  4. Very specific:

    If the rule is about visual/design quality: design-system usage, tokens, component reuse, UI copy → design.md.

    line 33
  5. Very specific:

    If the rule is about where files live, when files/directories are warranted, or how things are named → file_structure.md.

    line 34
  6. Very specific:

    If the rule references Sculptor-specific frontend hooks, atoms, file paths, or our data-flow conventions (e.g.

    line 35
  7. Very specific:

    If the rule is purely about React's framework primitives and would apply in any React codebase → react.md.

    line 36
  8. Very specific:

    When in doubt for frontend rules, prefer sculptor.md over react.md.

    line 37
  9. Very specific:

    Use no_ prefix for patterns that should not exist (e.g., no_effect_chains, no_sleep_then_assert)

    line 77
  10. Very specific:

    Use use_ prefix for prescriptive positive patterns (e.g., use_derived_atoms, use_expect_not_assert)

    line 78
  11. Very specific:

    Use a descriptive noun/adjective for structural issues (e.g., monolithic_component, unstable_list_keys)

    line 79
  12. Distinctive:

    Only include code examples when absolutely necessary.

    line 83
  13. Distinctive:

    Place the new rule near related rules in the chosen file.

    line 85

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Add a Review Rule

Add a new issue type to one of Sculptor's review-rule docs to prevent a class of issues from recurring.

The review-rule docs:

  • docs/development/review/react.md — generic React rules that would apply in any React codebase: effects, state, refs, render purity, performance, props, lists.
  • docs/development/review/sculptor.md — Sculptor-specific frontend conventions: backend data hooks (WS-pushed atoms, HTTP-pulled TanStack queries), Jotai atom usage, component-level invariants tied to our codebase.
  • docs/development/review/design.md — design quality judgments a linter can't make: Radix-first component usage, correct token selection, reuse of shared components, consistent UI copy.
  • docs/development/review/file_structure.md — file placement, feature layout, and naming: code located with its feature, kind-directory anatomy, helper/subfeature thresholds, component naming and domain vocabulary.
  • docs/development/review/integration_tests.md — Sculptor integration test rules: Playwright assertion patterns, test isolation, POM usage, flaky-pattern avoidance.

Input

The user provides a description of the problem — this could be:

  • A bug they just fixed and want to prevent in the future
  • A code pattern they noticed during review that should be flagged
  • A flaky test or test pattern that should be caught earlier
  • A link to a file/line or diff that demonstrates the issue

Steps

  1. Read all the review docs listed above to understand the existing rules, their format, and their naming conventions.
  2. Decide which file the new rule belongs in:
    • If the rule is about Playwright tests, integration test patterns, or test isolation/structure → integration_tests.md.
    • If the rule is about visual/design quality: design-system usage, tokens, component reuse, UI copy → design.md.
    • If the rule is about where files live, when files/directories are warranted, or how things are named → file_structure.md.
    • If the rule references Sculptor-specific frontend hooks, atoms, file paths, or our data-flow conventions (e.g. useUnifiedStream, BackendQueryResult, workspaceAtomFamily) → sculptor.md.
    • If the rule is purely about React's framework primitives and would apply in any React codebase → react.md.
    • When in doubt for frontend rules, prefer sculptor.md over react.md; revisit if the rule turns out to be more generic than expected.
  3. Determine whether an existing rule already covers the issue (check all the docs). If it does, tell the user which rule covers it and ask if they'd like to refine that rule instead. Do not add a duplicate.
  4. Draft a new rule following the exact format of existing rules in the chosen file.

    For react.md and sculptor.md (flat list, ## rule_name headings):

    ---
    
    ## `snake_case_rule_name`
    
    **Question:** A yes/no question that a reviewer can ask about the code.
    
    One or two paragraphs explaining why this is a problem and what the correct approach is.
    
    **What to look for:**
    - Concrete pattern or code smell to search for
    - Another pattern
    
    **Fix:** (optional) Brief description of how to fix it.
    
    **Exceptions:** (optional) Cases where this pattern is acceptable.

    For integration_tests.md (sectioned, ### rule_name inside an existing ## Section):

    ---
    
    ### `snake_case_rule_name`
    
    **Question:** ...
    
    [rest is the same as above, but the heading is `###` and the rule lives
    under one of the existing `## Section` groupings — pick the section that
    matches the rule's topic, e.g. "Playwright Assertions", "Test Isolation",
    "Test Structure"]
  5. Choose a clear snake_case name that describes the problem (not the fix). Follow the naming conventions:
    • Use no_ prefix for patterns that should not exist (e.g., no_effect_chains, no_sleep_then_assert)
    • Use use_ prefix for prescriptive positive patterns (e.g., use_derived_atoms, use_expect_not_assert)
    • Use a descriptive noun/adjective for structural issues (e.g., monolithic_component, unstable_list_keys)
  6. Write the rule to be generic — it should describe a class of issues, not a single instance. Strip out details specific to the user's particular bug (component names, variable names, business logic, Linear ticket IDs). For sculptor.md and integration_tests.md rules, naming our codebase concepts is fine (and expected); for react.md rules, the content should apply in any React codebase. The "What to look for" section should describe concrete, recognizable patterns a reviewer can spot in code.
  7. Only include code examples when absolutely necessary. Lean on the description, explanation, and "What to look for" patterns to convey the rule. The rule should be self-contained without code. Test rules sometimes benefit more from a "Bad/Good" pair because Playwright APIs are pattern-heavy.
  8. Place the new rule near related rules in the chosen file. Use your judgement — group it with rules about similar topics (effects, state, atoms, refs, performance, Playwright assertions, test isolation, etc.).
  9. Show the user the new rule (and which file you're adding it to) and ask for confirmation before writing it to the file.

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.