git:20260716.6355db6 to git:20261010.cd73169

1 added, 1 removed. Audit A to A.

---

name: bosskuai-coding-best-practices

- description: Use this for implementation quality, maintainability, readability, testing expectations, error handling, naming, and pragmatic best-practice checks that still fit the current repo conventions.

+ description: "Use when writing or reviewing code for quality: maintainability, readability, testing expectations, error handling, naming, and best-practice checks that fit repo conventions."

---

# BosskuAI Coding Best Practices

Use this skill when writing or reviewing code that should be easy to change, hard to misuse, and aligned with the existing codebase.

## Operating principles

- Prefer boring, readable code over clever code.

- Follow current repo conventions unless they are clearly harmful.

- Optimize for the three expensive failures: wrong behavior, production breakage, and code that is hard to change.

- For new behavior, bug fixes, and risky refactors: prefer test-first or test-guided work when practical.

- Debug with hypotheses, not random edits.

## What good code looks like

- single-responsibility functions and modules

- explicit side effects and error paths

- meaningful names

- shallow control flow with guard clauses

- no hidden shared mutable state

- validation at system boundaries

- tests or verification that prove the claimed behavior

## Common problems to catch

- god functions or objects

- primitive obsession where domain values need stronger types

- boolean traps and unreadable call sites

- swallowed exceptions

- magic values

- copy-paste logic drift

- shotgun surgery across too many files for one behavior

## Local decision guide

- local cleanup: one function or module is unclear but isolated

- revamp: the same structural problem repeats across many files

- architecture escalation: boundaries or contracts are the real problem

Load `bosskuai-code-revamp` or `bosskuai-software-architecture` when the issue is bigger than a local fix.

## Verification bias

- reproduce before fixing when debugging

- add or run the narrowest test that proves the behavior

- re-read the saved diff before declaring success

- call out what could not be verified

## Guardrails

- Do not impose a foreign pattern or abstraction just because it is fashionable.

- Do not add abstraction without repeated need.

- Do not mix a broad refactor into a bug fix unless the user asked for both.

- Do not mirror a bad existing pattern silently; fix proportionally and call it out.

## Output

Return:

- conventions observed

- findings or improvement opportunities

- whether the change should stay local, become a revamp, or escalate

- testing guidance or verification gaps

## References

- `../../references/checklists/coding-best-practices-checklist.md`

- `../../references/playbooks/coding-best-practices-playbook.md`

- `../../references/checklists/engineering-delivery-checklist.md`