Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions plugins/engineering-playbook/skills/code-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ Use those standards as hard review criteria, not background suggestions.
diff, commit diff, staged changes, or working-tree changes.
2. Inspect every changed file line by line. For each changed class, method,
function, variable, route, config value, migration, test, and dependency
boundary, check whether the implementation is correct and whether the names
reveal the real behavior.
boundary, check whether the implementation is correct and whether the text
and names reveal the real behavior.
3. Read surrounding code until the intent, call paths, data flow, side effects,
and failure behavior are clear. Do not review a line in isolation when nearby
code changes its meaning.
Expand All @@ -45,6 +45,9 @@ Use those standards as hard review criteria, not background suggestions.
6. Prefer small, local fixes that preserve the existing architecture. Suggest
broader redesign only when the local fix would hide a deeper correctness or
maintainability problem.
7. Report truthful naming violations as `Normal` severity by default. Escalate
only when the misleading name creates a blocker-level correctness, security,
or data risk.

## Output Format

Expand Down
12 changes: 10 additions & 2 deletions plugins/engineering-playbook/skills/coding-standards/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,6 @@ description: >-
private/protected method or dedicated class with a name that explains the
intent. A reader should understand what the logic means from the name before
reading the implementation.
- Name methods, classes, variables, and use cases after what they actually do,
including important side effects. Do not use names that hide behavior.
- Avoid negative boolean names for methods, variables, value objects, and
persisted fields. Prefer positive names such as `isEnabled` or
`isPubliclyAvailable` instead of `isDisabled`, `isPaused`, or other names
Expand All @@ -28,6 +26,16 @@ description: >-
`does...` only for methods that return `bool` and do not throw.
- In PHP tests, mark test methods with the `#[Test]` attribute instead of the `test...` prefix or `@test` docblock annotation.

## Rule: Truthful Naming
All text and names must tell the truth about the implementation they represent.

1. Name classes, methods, variables, use cases, tests, comments, and labels
after what they actually do or mean.
2. Include important side effects, boundaries, and failure behavior in the name
when omitting them would mislead the reader.
3. Prefer renaming over hiding behavior behind vague, aspirational, or
overly-polished language.

## Rule: Hexagonal Architecture
Follow hexagonal architecture as the baseline.

Expand Down