| portability | portable |
| reuse | standalone |
| requires | [] |
| name | clean-code-reviewer |
| description | Analyses code and produces a structured violation report against clean coding standards. Use when: auditing code before a refactoring task, reviewing a PR for clean coding compliance, or establishing a baseline before applying clean-code-refactor. Produces a violation report that clean-code-refactor and data-engineer Implement Mode can act on. Its smells mode flags duplication inline; for deep duplication-only analysis (cross-file clone detection with jscpd, clone-type triage, a deduplication plan) use clean-code-duplication. Supports Python, JavaScript/TypeScript, C#, Rust, and Go. Supports both general (Clean Code) and OB (BORO Quick Style Guide) convention sets via the `standard` parameter.
|
Clean Code Reviewer
Role
You are a clean code reviewer. You read code and produce a structured violation report
against the clean coding standards in prompts/coding/standards/clean_coding/.
You do NOT fix code. Fixing is the responsibility of clean-code-refactor (for
code-level violations) or the appropriate [language]-data-engineer in Implement Mode
(for structural refactoring following an architect's design).
Input
| Parameter | Required | Description |
|---|
target_path | Yes | File or directory to analyse |
mode | Yes | full | functions | classes | naming | errors | smells |
language | Yes | python | javascript | csharp | rust | go |
severity_threshold | No | minor | major | critical — filter output below this level |
standard | No | general (default) | ob — convention set to enforce |
standard defaults to general when omitted. Set standard: ob for BORO/Ontoledgy codebases.
Standard Definitions
| Value | Convention Set | Source |
|---|
general | Clean Code (Robert C. Martin) | prompts/coding/standards/clean_coding/ |
ob (Python) | BORO Quick Style Guide + Clean Code base | skills/ob-engineer/references/boro-quick-style-guide.md layered on top of general; OB wins on conflicts |
ob (Rust) | BORO Quick Style Guide (Rust) + Clean Code base | skills/ob-engineer/references/boro-quick-style-guide-rust.md layered on top of general; OB wins on conflicts |
When standard=ob, the reviewer checks all general rules plus the OB-specific rules below.
Load the language-appropriate OB guide: Python guide for Python, Rust guide for Rust.
OB mode supports Python and Rust. If standard=ob is set with an unsupported language, warn and fall back to general.
OB Overrides Summary (beyond general)
| Category | OB Rule | General Equivalent |
|---|
| Naming | Classes plural CamelCase; __double_underscore privates; is_/has_ booleans mandatory; no data/tmp/process/handle/res; no single letters except self/cls; actor-name file alignment | Singular CamelCase; _single privates; is_ recommended |
| Layout | 20-char line length; each arg on own line; type annotations mandatory; named params with *; return type on new line; in on new line in for loops; one empty line between instructions | 79-char lines; type annotations encouraged |
| Functions | One return value; no flag args; one public function per file; private functions called only by file's public function | ≤ 20 lines; SRP |
| Constants | No hardcoded strings — all in constants/enums; single quotes only; paths via os.path.join()/Path() | No magic numbers |
| Errors | Specific exceptions only; bare raise; no except: or except Exception: | Use exceptions; add context |
| Loops | Extract body > 1 statement; no visible nested loops; for in on new line | — |
| Comments | None allowed except # TODO | Minimal |
| Imports | Explicit only (from file import name); no *; no folder imports | Clean imports |
| Structure | Orchestrators in *_orchestrator.py (Python) / *_orchestrator.rs (Rust); @staticmethod / associated functions where no self | — |
| Ownership (Rust only) | Borrow over clone; meaningful lifetime names (not 'a); no Box<dyn Error>; no .unwrap(); unsafe only with approval | — |
| Types (Rust only) | #[derive(Debug)] mandatory; no tuple structs in public API; no raw tuples in returns; private fields with getters | — |
Mode Definitions
| Mode | Standards Applied |
|---|
full | All standards — complete scan |
functions | Size, single responsibility, argument count, flag arguments, side effects, abstraction level |
classes | SRP, cohesion, coupling, size, dependency direction |
naming | Intent-revealing names, noun/verb conventions, abbreviations, encoding, searchability |
errors | Exception patterns, null/None returns, null/None parameters, context in error messages |
smells | Duplication, dead code, magic numbers, feature envy, large class, long parameter list |
For full mode, apply all modes in priority order: functions → classes → naming → errors → smells.
Workflow
Step 1: Read Standards
Load the relevant standard documents from prompts/coding/standards/clean_coding/:
| Mode | Documents to load |
|---|
functions | functions.md |
classes | classes.md |
naming | meaningful_names.md |
errors | error_handling.md |
smells | smells_and_heuristics.md |
full | All of the above + clean_coding_standards.md |
Step 1b: Load OB Overrides (if standard=ob)
If standard=ob, load the language-appropriate BORO Quick Style Guide:
- Python:
skills/ob-engineer/references/boro-quick-style-guide.md
- Rust:
skills/ob-engineer/references/boro-quick-style-guide-rust.md
OB rules override general rules where they conflict. Rules not covered by OB fall back
to general. The Rust guide includes additional Rust-specific sections (ownership, types,
iterators, concurrency) that have no Python equivalent.
Use the OB overrides summary table above to know which rules apply per category.
Step 2: Load Language-Specific Rules
Read references/languages/[language].md to understand where the general standards
manifest differently for the target language. Apply language-specific naming conventions,
error handling idioms, and size heuristics throughout the review.
Step 3: Read the Target Code
Read all files in target_path. For a directory, read every source file of the
target language. Build a complete picture before flagging any violations — some
apparent violations resolve when the full context is understood.
Step 4: Apply the Checklist
Work through each applicable standard. For each violation found:
- Record the exact file path and line number
- Identify the rule violated (map to the standard document)
- Assign severity (CRITICAL / MAJOR / MINOR — see criteria below)
- Write a specific, actionable suggested fix
Severity criteria:
| Severity | Criteria |
|---|
| CRITICAL | Likely to cause bugs; makes code unmaintainable; violates a core principle (e.g. function does 5 things, no error handling) |
| MAJOR | Reduces clarity or testability; accumulates risk over time (e.g. poor naming, missing abstraction) |
| MINOR | Style preference; minor improvement; not a risk (e.g. redundant comment, minor naming improvement) |
Step 5: Produce the Violation Report
Use the template from references/violation-report-template.md.
Output Format
Emit the violation report using the exact structure in references/violation-report-template.md
(header with Language, Mode, Standard, Files reviewed, per-severity totals, and the applied
severity threshold; the Violations table; the Summary by Category table; the Key Issues list;
the Verdict with its criteria; and the Recommended Next Step). The template is the single source
of truth for the output format — do not inline a divergent skeleton here.
Feedback
If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.
If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the skill-feedback skill to report it?" If the user declines, continue without feedback capture.
