0 Fork 0

Files

T

ZacharyZhang-NY e74dafcd36 Silence render-disposed spam, unbreak bundled skills, drop board wake

Three independently ugly bugs that all fed the same log flood:

* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
  to stderr via `console.error`. When the worker fans a second
  agent-event past a reloading renderer, we produced thousands of
  identical lines and stalled the main loop on stderr I/O. Added a
  `mainFrame.detached` guard so the send is short-circuited before
  Electron's own catch block fires, and installed a targeted filter in
  `suppress-warnings.ts` (now actually imported from the entry point)
  so the specific `console.error("Error sending from webFrameMain:"…)`
  noise never reaches the terminal. Any other payload still surfaces.

* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
  target when an agent replied to `__board__` — `wakeAgentIfPossible`
  then called `db.getAgent("__board__")`, threw, and the dispatcher
  kept repeating on every send. Strip `HUMAN_SENDER_ID` at
  `resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
  heartbeat so a stray caller (future automation fan-out) cannot
  reintroduce the crash.

* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
  diverges from its parent directory. The four bundled `my-writing-style`
  copies declared `name: writing-style-skill`, so every install emitted
  a warning and dropped the skill. They also lived as orphan gitlinks
  (mode 160000 without .gitmodules), and the global `*.md` gitignore
  hid every other SKILL.md from version control. Fixed the frontmatter
  to match the dir, converted the dangling submodules to plain trees,
  and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
  catalogue instead of silently losing it.

2026-04-20 08:13:48 -04:00

6.9 KiB

Raw Blame History

name, description

name	description
clean-code	Use when writing, reviewing, or refactoring code for maintainability and readability. Triggers on code reviews, naming discussions, function design, error handling, and test writing. Based on Robert C. Martin's Clean Code handbook with modern corrections.

Robert C. Martin (Uncle Bob) Clean Code Best Practices

Comprehensive software craftsmanship guide based on Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship", updated with modern corrections where the original 2008 advice has been superseded. Contains 48 rules across 10 categories, prioritized by impact to guide code reviews, refactoring decisions, and new development. Examples are primarily in Java but principles are language-agnostic.

When to Apply

Reference these guidelines when:

Writing new functions, classes, or modules
Naming variables, functions, classes, or files
Reviewing code for maintainability issues
Refactoring existing code to improve clarity
Writing or improving unit tests
Wrapping third-party dependencies

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Meaningful Names	CRITICAL	`name-`
2	Functions	CRITICAL	`func-`
3	Comments	HIGH	`cmt-`
4	Formatting	HIGH	`fmt-`
5	Error Handling	HIGH	`err-`
6	Objects and Data Structures	MEDIUM-HIGH	`obj-`
7	Boundaries	MEDIUM-HIGH	`bound-`
8	Classes and Systems	MEDIUM-HIGH	`class-`
9	Unit Tests	MEDIUM	`test-`
10	Emergence and Simple Design	MEDIUM	`emerge-`

Quick Reference

1. Meaningful Names (CRITICAL)

name-intention-revealing - Use names that reveal intent
name-avoid-disinformation - Avoid misleading names
name-meaningful-distinctions - Make meaningful distinctions
name-pronounceable - Use pronounceable names
name-searchable - Use searchable names
name-avoid-encodings - Avoid encodings in names
name-class-noun - Use noun phrases for class names
name-method-verb - Use verb phrases for method names

2. Functions (CRITICAL)

func-small - Keep functions small
func-one-thing - Functions should do one thing
func-abstraction-level - Maintain one level of abstraction
func-minimize-arguments - Minimize function arguments
func-no-side-effects - Avoid side effects
func-command-query-separation - Separate commands from queries
func-dry - Do not repeat yourself

3. Comments (HIGH)

cmt-express-in-code - Express yourself in code, not comments
cmt-explain-intent - Use comments to explain intent
cmt-avoid-redundant - Avoid redundant comments
cmt-avoid-commented-out-code - Delete commented-out code
cmt-warning-consequences - Use warning comments for consequences

4. Formatting (HIGH)

fmt-vertical-formatting - Use vertical formatting for readability
fmt-horizontal-alignment - Avoid horizontal alignment
fmt-team-rules - Follow team formatting rules
fmt-indentation - Respect indentation rules

5. Error Handling (HIGH)

err-use-exceptions - Separate error handling from happy path
err-write-try-catch-first - Write try-catch-finally first
err-provide-context - Provide context with exceptions
err-define-by-caller-needs - Define exceptions by caller needs
err-avoid-null - Avoid returning and passing null

6. Objects and Data Structures (MEDIUM-HIGH)

obj-data-abstraction - Hide data behind abstractions
obj-data-object-asymmetry - Understand data/object anti-symmetry
obj-law-of-demeter - Follow the Law of Demeter
obj-avoid-hybrids - Avoid hybrid data-object structures
obj-dto - Use DTOs for data transfer

7. Boundaries (MEDIUM-HIGH)

bound-wrap-third-party - Wrap third-party APIs
bound-learning-tests - Write learning tests for third-party code

8. Classes and Systems (MEDIUM-HIGH)

class-small - Keep classes small
class-cohesion - Maintain class cohesion
class-organize-for-change - Organize classes for change
class-isolate-from-change - Isolate classes from change
class-separate-concerns - Separate construction from use

9. Unit Tests (MEDIUM)

test-first-law - Follow the three laws of TDD
test-keep-clean - Keep tests clean
test-one-assert - One concept per test
test-first-principles - Follow FIRST principles
test-build-operate-check - Use Build-Operate-Check pattern

10. Emergence and Simple Design (MEDIUM)

emerge-simple-design - Follow the four rules of simple design
emerge-expressiveness - Maximize expressiveness

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

6.9 KiB Raw Blame History