software-clean-code-standard
Cross-language clean code standard with stable CC-* rule IDs. Use when writing/reviewing code, defining team standards, or citing lint findings.
What this skill does
# Clean Code Standard — Quick Reference
This skill is the authoritative clean code standard for this repository's shared skills. It defines stable rule IDs (`CC-*`), how to apply them in reviews, and how to extend them safely via language overlays and explicit exceptions.
**Modern Best Practices (January 2026)**: Prefer small, reviewable changes and durable change context. Use RFC 2119 normative language consistently. Treat security-by-design and secure defaults as baseline (OWASP Top 10, NIST SSDF). Build observable systems (OpenTelemetry). For durable links and current tool choices, consult `data/sources.json`.
---
## Quick Reference
| Task | Tool/Framework | Command | When to Use |
|------|-----|---------|-------------|
| Cite a standard | `CC-*` rule ID | N/A | PR review comments, design discussions, postmortems |
| Categorize feedback | `CC-NAM`, `CC-ERR`, `CC-SEC`, etc. | N/A | Keep feedback consistent without "style wars" |
| Add stack nuance | Language overlay | N/A | When the base rule is too generic for a language/framework |
| Allow an exception | Waiver record | N/A | When a rule must be violated with explicit risk |
| Reuse shared checklists | `assets/checklists/` | N/A | When you need product-agnostic review/release checklists |
| Reuse utility patterns | `references/*-utilities.md` | N/A | When extracting shared auth/logging/errors/resilience/testing utilities |
## When to Use This Skill
- Defining or enforcing clean code rules across teams and languages.
- Reviewing code: cite `CC-*` IDs and avoid restating standards in reviews.
- Building automation: map linters/CI gates to `CC-*` IDs.
- Resolving recurring review debates: align on rule IDs, scope, and exceptions.
## When NOT to Use This Skill
- **Deep security audits**: Use [software-security-appsec](../software-security-appsec/SKILL.md) for OWASP/SAST deep dives beyond `CC-SEC-*` baseline.
- **Review workflow mechanics**: Use [software-code-review](../software-code-review/SKILL.md) for PR workflow, reviewer assignment, and feedback patterns.
- **Refactoring execution**: Use [qa-refactoring](../qa-refactoring/SKILL.md) for step-by-step refactoring patterns and quality gates.
- **Architecture decisions**: Use [software-architecture-design](../software-architecture-design/SKILL.md) for system-level tradeoffs beyond code-level rules.
## Decision Tree: Base Rule vs Overlay vs Exception
```text
Feedback needed: [What kind of guidance is this?]
├─ Universal, cross-language rule? → Add/modify `CC-*` in `references/clean-code-standard.md`
│
├─ Language/framework-specific nuance? → Add overlay entry referencing existing `CC-*`
│
└─ One-off constraint or temporary tradeoff?
├─ Timeboxed? → Add waiver with expiry + tracking issue
└─ Permanent? → Propose a new rule or revise scope/exception criteria
```
---
## Navigation
**Resources**
- [references/clean-code-standard.md](references/clean-code-standard.md)
- [references/code-quality-operational-playbook.md](references/code-quality-operational-playbook.md) — Legacy operational playbook (RULE-01–RULE-13)
- [references/clean-code-operational-checklist.md](references/clean-code-operational-checklist.md)
- [references/clean-coder-operational-checklist.md](references/clean-coder-operational-checklist.md)
- [references/code-complete-operational-checklist.md](references/code-complete-operational-checklist.md)
- [references/pragmatic-programmer-operational-checklist.md](references/pragmatic-programmer-operational-checklist.md)
- [references/practice-of-programming-operational-checklist.md](references/practice-of-programming-operational-checklist.md)
- [references/working-effectively-with-legacy-code-operational-checklist.md](references/working-effectively-with-legacy-code-operational-checklist.md)
- [references/art-of-clean-code-operational-checklist.md](references/art-of-clean-code-operational-checklist.md)
- [references/refactoring-operational-checklist.md](references/refactoring-operational-checklist.md)
- [references/design-patterns-operational-checklist.md](references/design-patterns-operational-checklist.md)
- [references/functional-programming-patterns.md](references/functional-programming-patterns.md) — Result/Either types, pipe/compose, immutability, pure functions, railway-oriented programming, CC-* rule mapping
- [references/code-complexity-metrics.md](references/code-complexity-metrics.md) — Cyclomatic/cognitive complexity, Halstead metrics, nesting depth, tooling (ESLint, SonarQube, CodeClimate), refactoring triggers
- [data/sources.json](data/sources.json) — Durable external references for review, security-by-design, and observability
- [CONVENTIONS.md](CONVENTIONS.md) — Skill structure and validation conventions
- [SKILL-TEMPLATE.md](SKILL-TEMPLATE.md) — Copy-paste starter for new skills
- [sources-schema.json](sources-schema.json) — JSON schema for `data/sources.json`
- [skill-dependencies.json](skill-dependencies.json) — Related-skills dependency graph
**Templates**
- [assets/checklists/backend-api-review-checklist.md](assets/checklists/backend-api-review-checklist.md)
- [assets/checklists/secure-code-review-checklist.md](assets/checklists/secure-code-review-checklist.md)
- [assets/checklists/frontend-performance-a11y-checklist.md](assets/checklists/frontend-performance-a11y-checklist.md)
- [assets/checklists/mobile-release-checklist.md](assets/checklists/mobile-release-checklist.md)
- [assets/checklists/ux-design-review-checklist.md](assets/checklists/ux-design-review-checklist.md)
- [assets/checklists/ux-research-plan-template.md](assets/checklists/ux-research-plan-template.md)
**Utility Patterns**
- [references/auth-utilities.md](references/auth-utilities.md)
- [references/error-handling.md](references/error-handling.md)
- [references/config-validation.md](references/config-validation.md)
- [references/resilience-utilities.md](references/resilience-utilities.md)
- [references/logging-utilities.md](references/logging-utilities.md)
- [references/observability-utilities.md](references/observability-utilities.md)
- [references/testing-utilities.md](references/testing-utilities.md)
- [references/llm-utilities.md](references/llm-utilities.md)
**Related Skills**
- [../software-code-review/SKILL.md](../software-code-review/SKILL.md) — Review workflow and judgment; cite `CC-*` IDs
- [../software-security-appsec/SKILL.md](../software-security-appsec/SKILL.md) — Security deep dives beyond baseline `CC-SEC-*`
- [../qa-refactoring/SKILL.md](../qa-refactoring/SKILL.md) — Refactoring execution patterns and quality gates
- [../software-architecture-design/SKILL.md](../software-architecture-design/SKILL.md) — System-level tradeoffs and boundaries
---
## Optional: AI/Automation
- Map automation findings to `CC-*` IDs (linters, SAST, dependency scanning) so humans can review impact, not tooling noise.
- Keep AI-assisted suggestions advisory; human reviewers approve/deny with rule citations (https://conventionalcomments.org/).
---
## Trend Awareness Protocol
**IMPORTANT**: When users ask recommendation questions about clean code standards, linters, or code quality tools, you MUST use a web search capability (if available) to check current trends before answering. If web search is unavailable, say so and answer using `data/sources.json`, clearly flagging that the recommendation may be stale.
### Trigger Conditions
- "What's the best linter for [language]?"
- "What should I use for [code quality/static analysis]?"
- "What's the latest in clean code practices?"
- "Current best practices for [code standards/formatting]?"
- "Is [ESLint/Prettier/Biome] still relevant in 2026?"
- "[Biome] vs [ESLint] vs [other]?"
- "Best static analysis tool for [language]?"
### Required Searches
1. Search: `"clean code best practices 2026"`
2. Search: `"[specific linter] vs alternatives 2026"`
3. Search: `"code quality tools trends 2026"`
4. Search: `"[language] linter comparison 2026"`
### What to Report
AfRelated in Writing & Docs
jax-development
IncludedUse this skill when the user is writing, debugging, profiling, refactoring, reviewing, benchmarking, parallelising, exporting, or explaining JAX code, or when they mention JAX, jax.numpy, jit, grad, value_and_grad, vmap, scan, lax, random keys, pytrees, jax.Array, sharding, Mesh, PartitionSpec, NamedSharding, pmap, shard_map, Pallas, XLA, StableHLO, checkify, profiler, or the JAX repo. It helps turn NumPy or PyTorch-style code into pure functional JAX, fix tracer/control-flow/shape/PRNG bugs, remove recompiles and host-device syncs, choose transforms and sharding strategies, inspect jaxpr/lowering/IR, and benchmark compiled code correctly.
nature-article-writer
IncludedDrafts, rewrites, diagnostically critiques, and style-calibrates primary research manuscripts for Nature and Nature Portfolio journals. Use when the user wants a Nature-style title, summary paragraph or abstract, introduction, results, discussion, methods, figure legends, presubmission enquiry, cover letter, reviewer response, or when a scientific draft sounds generic, jargon-heavy, structurally weak, or AI-ish and needs precise, broad-reader-friendly prose without inventing data, analyses, or references. Best for primary research articles and letters rather than reviews or press releases unless explicitly adapting one.
deckrd
IncludedDocument-driven framework that derives requirements, specifications, implementation plans, and executable tasks from goals through structured AI dialogue. Use when user says "write requirements", "create spec", "plan implementation", "derive tasks", "structure this feature", "break down into tasks", or "document this module". Also use for reverse engineering existing code into docs (/deckrd rev). Do NOT use for direct code writing — use /deckrd-coder after tasks are generated. Do NOT use when the user only wants to run or fix existing code without planning.
clinical-decision-support
IncludedGenerate professional clinical decision support (CDS) documents for pharmaceutical and clinical research settings, including patient cohort analyses (biomarker-stratified with outcomes) and treatment recommendation reports (evidence-based guidelines with decision algorithms). Supports GRADE evidence grading, statistical analysis (hazard ratios, survival curves, waterfall plots), biomarker integration, and regulatory compliance. Outputs publication-ready LaTeX/PDF format optimized for drug development, clinical research, and evidence synthesis.
handling-sf-data
IncludedSalesforce data operations with 130-point scoring. Use this skill to create, update, delete, bulk import/export, generate test data, and clean up org records using sf CLI and anonymous Apex. TRIGGER when: user creates test data, performs bulk import/export, uses sf data CLI commands, needs data factory patterns for Apex tests, or needs to seed/clean records in a Salesforce org. DO NOT TRIGGER when: SOQL query writing only (use querying-soql), Apex test execution (use running-apex-tests), or metadata deployment (use deploying-metadata).
accelint-ac-to-playwright
IncludedConvert and validate acceptance criteria for Playwright test automation. Use when user asks to (1) review/evaluate/check if AC are ready for automation, (2) assess if AC can be converted as-is, (3) validate AC quality for Playwright, (4) turn AC into tests, (5) generate tests from acceptance criteria, (6) convert .md bullets or .feature Gherkin files to Playwright specs, (7) create test automation from requirements. Handles both bullet-style markdown and Gherkin syntax with JSON test plan generation and validation.