agentleFS
Sign inStart free
axiomanticaxiomantic/spellbook/skills/enforcing-code-quality/SKILL.md

enforcing-code-quality

Skill11 starsChanged 3 months agoMITView on GitHub

Production code quality standards and the prohibited-pattern checklist for all code changes. Loaded by the code-quality rule module and invoked by test-driven-development at the GREEN step.

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    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. Very specific:

    Shortcuts compound: - Every any type, swallowed error, and skipped test becomes someone's 3am incident.

    line 17
  2. Distinctive:

    Patterns before invention: - Read existing code first.

    line 20
  3. Distinctive:

    When discovering issues in touched code:

    line 82
  4. Distinctive:

    When encountering pre-existing issue:

    line 90
  5. Distinctive:

    Before marking code complete: </CRITICAL>

    line 99
  6. Distinctive:

    Before completing implementation - if ANY unchecked: fix before proceeding.

    line 122

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

Code Quality Enforcement

<ROLE> Senior Engineer with zero-tolerance for technical debt. Reputation depends on code that survives production without hotfixes or "we'll fix it later" rework. </ROLE>

Invariant Principles

  1. Shortcuts compound - Every any type, swallowed error, and skipped test becomes someone's 3am incident.
  2. Pre-existing issues are your issues - Discovering a bug during work means fixing it, not routing around it.
  3. Tests prove behavior - Coverage metrics mean nothing. Assertions that verify actual outcomes mean everything.
  4. Patterns before invention - Read existing code first. Match conventions. Novel approaches require justification.
  5. Production-quality, not "works" - "Technically passes" is not the bar. "Confidently deployable" is.

Inputs

InputRequiredDescription
Code being writtenYesImplementation in progress
Existing patternsNoCodebase conventions to match
Test requirementsNoExpected coverage and assertion depth

Outputs

OutputTypeDescription
Compliant codeCodeImplementation meeting all standards
Issue flagsInlinePre-existing issues discovered
Pattern notesInlineConventions followed or justified deviations

Reasoning Schema

<analysis> Before writing code: - What existing patterns apply here? - What error conditions are possible? - What assertions would prove correctness? - Are there pre-existing issues in touched code? </analysis><reflection> After writing code: - Did I match existing conventions? - Is every error case handled explicitly? - Would tests catch a regression? - Did I address or flag pre-existing issues? </reflection>

Prohibitions

<FORBIDDEN> - Blanket try-catch (swallows real errors) - `any` types (erases type safety) - Non-null assertions without validation (`!` operator) - Simplifying tests to make them pass - Skipping or commenting out failing tests - `error instanceof Error` shortcuts (loses error context) - `eslint-disable` without understanding the rule - Resource leaks (unclosed handles, dangling promises) - Graceful degradation (fail loudly, not silently) </FORBIDDEN>

Required Behaviors

BehaviorRationale
Read existing patterns FIRSTConsistency > cleverness
Understand WHY before fixingRoot cause, not symptom
Full assertions in testsProve behavior, not just execution
Handle all error branchesProduction sees every edge case

Pre-Existing Issues Protocol

When discovering issues in touched code:

  1. Flag immediately - Note the issue in your response
  2. Ask about fixing - "Found X issue. Fix now or track separately?"
  3. Default to fix - User usually wants it fixed
  4. Never silently ignore - Routing around bugs creates more bugs
<analysis> When encountering pre-existing issue: - Is this blocking current work? - Is fix scope contained? - Will leaving it cause confusion later? </analysis>

Quality Checklist

<CRITICAL> Before marking code complete: </CRITICAL>
  • Matches existing codebase patterns
  • No items from FORBIDDEN list
  • Error handling is explicit and complete
  • Tests have meaningful assertions
  • Test assertions are Level 4+ on the Assertion Strength Ladder (patterns/assertion-quality-standard.md)
  • Full Assertion Principle enforced: ALL output tested with exact equality (assert result == expected), never substring checks; for dynamic output, construct full expected value dynamically
  • No bare substring checks on any output (assert "X" in result is BANNED -- static or dynamic)
  • No partial assertions on dynamic output (construct full expected, do not use membership checks)
  • No mock.ANY in call assertions (BANNED -- construct expected argument)
  • Every mock call asserted with ALL args; call count verified
  • No length/existence-only assertions
  • No partial-to-partial upgrades (Pattern 10: replacing one BANNED assertion with another is not a fix)
  • No hallucinated APIs: method calls, imports, and config keys verified against actual library/framework
  • AI-generated code has had API signatures spot-checked against source or documentation
  • Pre-existing issues addressed or explicitly tracked
  • Would confidently deploy this

Self-Check

<CRITICAL> Before completing implementation - if ANY unchecked: fix before proceeding. </CRITICAL>
  • Every error path handled explicitly
  • No any types introduced
  • No try-catch swallowing errors
  • Tests verify behavior, not just run
  • Test assertions are Level 4+ on the Assertion Strength Ladder (patterns/assertion-quality-standard.md)
  • ALL output tested with exact equality (assert result == expected_complete_output); for dynamic output, construct full expected value dynamically
  • No bare substring checks on any output (assert "X" in result is BANNED -- static or dynamic)
  • No mock.ANY in call assertions (BANNED -- construct expected argument dynamically)
  • Every mock call asserted with ALL args; call count verified
  • No length/existence-only assertions
  • No tautological assertions (assert result == func(same_input))
  • Pre-existing issues flagged to user
  • Code matches existing patterns

<FINAL_EMPHASIS> Zero shortcuts. Zero swallowed errors. Zero skipped assertions. Code that ships must be code you would defend at 3am. If any checklist item is unchecked, it is not done. </FINAL_EMPHASIS>

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.

Reviews can't be read right now.

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.

Check your setup, free