Comprehensive spec-review

The best, most elegant and effective software systems are ones that are well-informed, well-planned, and verifiable. The final output is a plan/spec that can act as a reference doc, covering the problem/motivation, technical approach, deltas (what properties of the system will change once implemented), and verification criteria.

Your task is to review this spec from multiple expert perspectives to ensure that this spec meets our expectations and will result in solid implementations once it's in the hands of the engineers.

The bar: the design should be elegant, well-designed, minimal, maintainable, and not overengineered — something the team would be proud to ship. A spec that merely works but fails that bar is not done.

Efficacy Review

Run this one first. Every other lens checks that the thing being built is well-formed; this is the only one that checks it is the same thing as the stated problem.

• Restate the goal, then restate the mechanism. Do they close the same gap?
• For any goal about preventing something: what is the cheapest way to get the bad outcome anyway? Trace the path a hostile or indifferent user takes. If that path doesn't run through the changed code, the goal may not be met, no matter how good the change is.
• Which layer enforces it? A control in the client is a suggestion.
• Is the spec solving the problem, or solving the first solution someone proposed for it?