aposd-red-flag-review
Skill6 starsChanged 34 days agoMITView on GitHub
Review a diff, module, or design for complexity using the red flags from John Ousterhout's "A Philosophy of Software Design" (2018). Use when asked to review code or a design for maintainability, "is this too complex", "why is this hard to change", "design review", "check for shallow modules", "information leakage", or when a change touches module boundaries, interfaces, or splits one piece of logic into many small classes or steps. Use it even when the user never mentions the book. It audits an existing change and reports findings; use `codebase-design` when you are designing or deepening an interface from scratch.
In this repository79 other files it gives its agents.
- adr-phase-coverageSkill
- apple-on-device-aiSkill
- artifact-gatesSkill
- asc-app-create-uiSkill
- asc-build-lifecycleSkill
- asc-cli-usageSkill
- asc-crash-triageSkill
- asc-id-resolverSkill
- asc-localize-metadataSkill
- asc-metadata-syncSkill
- asc-notarizationSkill
- asc-ppp-pricingSkill
- asc-release-flowSkill
- asc-revenuecat-catalog-syncSkill
- asc-shots-pipelineSkill
- asc-signing-setupSkill
- asc-submission-healthSkill
- asc-subscription-localizationSkill
- asc-testflight-orchestrationSkill
- asc-wall-submitSkill
- asc-workflowSkill
- asc-xcode-buildSkill
- choose-boring-technologySkill
- ci-preflightSkill
- conways-lawSkill
- cost-routingSkill
- cost-tier-routingSkill
- cunninghams-lawSkill
- ddd-strategic-auditSkill
- ddd-tactical-reviewSkill
- debug-test-captureSkill
- developing-ios-appsSkill
- doerrs-lawSkill
- fitts-lawSkill
- fix-regression-guardSkill
- galls-lawSkill
- goodharts-lawSkill
- greenspuns-tenth-ruleSkill
- gsd-core-hooksSkill
- hofstadters-lawSkill
- hyrums-lawSkill
- ios-accessibilitySkill
- ios-simulator-boot-healthSkill
- kerckhoffs-principleSkill
- kernighans-lawSkill
- knuths-optimization-principleSkill
- lady-lovelaces-objectionSkill
- leaky-abstractionsSkill
- linuss-lawSkill
- mobile-ios-designSkill
- money-boundary-judgmentSkill
- moores-lawSkill
- no-deferSkill
- norvigs-lawSkill
- parkinsons-lawSkill
- peter-principleSkill
- postels-lawSkill
- post-fix-traceSkill
- qa-test-architectSkill
- rubber-duckSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Ask of the change (or the area it touches) whether any symptom is present.
- Distinctive: line 37
Vague or hard-to-pick name: if you cannot find a precise name, the thing probably does more than one job.
- Distinctive: line 53
Do not enforce these as rules.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
APOSD Red-Flag Review
Ousterhout's thesis: complexity is anything in a system's structure that makes it hard to understand or modify. It accumulates in small increments, so review is the cheapest place to stop it. This skill turns the book's diagnostics into a review pass. It is an audit: it reads a change and reports. It does not redesign. For redesign, hand off to codebase-design (deep-module vocabulary, seam placement, design-it-twice).
These are judgment heuristics, not metrics. Report evidence and a confidence, not a score.
Step 1: Diagnose with the three symptoms
Ask of the change (or the area it touches) whether any symptom is present. A symptom with no red flag behind it is still worth reporting.
| Symptom | Test |
| Change amplification | Would a plausible small future change (a new field, a renamed concept) require edits in many places? |
| Cognitive load | How much must a reader hold in their head to modify this safely: hidden ordering rules, flags, shared state, special cases? |
| Unknown unknowns | Is it unclear what else must change, or what could break? This is the worst symptom because nothing in the code warns you. |
Trace each symptom to a cause. There are only two:
- Dependencies: code cannot be understood or changed in isolation.
- Obscurity: important information is not obvious (vague names, undocumented invariants, hidden coupling).
Step 2: Scan for red flags
For each, cite file:line and say what the reader pays for it.
- Shallow module: the interface is nearly as complex as the implementation. Test: delete it. If the complexity just moves to callers, it was earning its keep; if nothing is lost, it was a pass-through.
- Information leakage: one design decision (a file format, a protocol, a table layout, an ordering) is encoded in more than one module, so changing it means editing several.
- Temporal decomposition: modules are split by when things happen (read, then parse, then write) instead of by what knowledge each hides. It is a common cause of leakage, because the same format knowledge ends up in both the reader and the writer.
- Pass-through method: a method that only forwards its arguments to a similar signature elsewhere, adding no abstraction of its own.
- Pass-through variable: a value threaded through layers that don't use it. Consider whether a shared object or a different owner removes the threading.
- Overexposure: a common-case use forces the caller to learn rarely needed features. Defaults should serve the common case.
- Vague or hard-to-pick name: if you cannot find a precise name, the thing probably does more than one job. A vague name is also a design smell, not only a style issue.
- Special-general mixture: a general-purpose module carries code specific to one caller or one use case.
- Conjoined methods: two pieces of code that cannot be understood without each other, though they live apart.
Step 3: Weigh before you report
The book's own caveat: the goal is lower total complexity, not a count of flags. Before reporting a finding, check:
- Is the "shallow" module an intentional seam that something actually varies across (two real adapters)? Then it is justified.
- Is the duplication a leak, or two decisions that merely look alike today?
- Would fixing it add more interface than it removes?
Drop findings that fail these checks. A short list of real findings beats a long list of nits.
Contested areas: present both sides
Do not enforce these as rules. If one comes up, state the default and the dissent.
- Comments: Ousterhout treats interface comments as a design tool (writing the comment first tests the abstraction) and wants them to capture intent, contracts, and non-obvious information. Robert Martin (Clean Code) distrusts comments and prefers descriptive names. Both accept comments for what code cannot express. Default: require a comment where intent or a contract is non-obvious; do not demand comments that restate the code.
- Method length: Ousterhout argues very short methods produce shallow interfaces and entangled pieces; Clean Code favors small functions. Flag over-decomposition only when the pieces cannot be understood independently, and say it is a trade-off.
Output
## APOSD review
Scope: <what was reviewed>
Symptoms: <which of the three, with the cause: dependencies / obscurity>
Findings (most costly first):
1. <red flag> — file:line — what it costs a reader/maintainer — suggested direction (one line) — confidence high/med/low
Not flagged on purpose: <seams or short methods you judged justified>
Hand-off: <codebase-design if a finding needs a redesign, otherwise none>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

