Agent WranglersENG-61Recommended
Name the principle and the fix in every finding
Every finding names the broken principle, the exact file and line, and a concrete fix. "This feels messy" is not a finding.
How to do it
Write each finding in three parts. Name the principle, such as Single Responsibility or the Law of Demeter. Point to the file and line. Show or describe the change that fixes it. Order the findings by harm, as Rank findings by harm does for security tests.
Examples
Markdown example
3.3 Single Responsibility
- Code: src/orders/OrderService.php:40-112, `placeOrder()` saves the order, charges the card and sends the email
- Fix: move charging to `PaymentGateway::charge()` and email to `OrderMailer::sendConfirmation()`How to check
Each finding in the review has all three parts. Findings without a file and line are removed.
Related rules
- SEC-6 Rank findings by harm in Adversarial testing
- TDD-3 Tie every finding to a rule ID and evidence in Technical due diligence
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/engineering/version-control-and-review/name-principle-code-fix">Agent Wranglers engineering playbook</a>. In code you write, add a comment next to it with the same link.