agentleFS
The-Artificer-of-Ciphers-LLCThe-Artificer-of-Ciphers-LLC/skills-from-the-artificer/aposd-red-flag-review/SKILL.md

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.

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
  1. Distinctive:

    Ask of the change (or the area it touches) whether any symptom is present.

    line 14
  2. Distinctive:

    Vague or hard-to-pick name: if you cannot find a precise name, the thing probably does more than one job.

    line 37
  3. Distinctive:

    Do not enforce these as rules.

    line 53

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

SymptomTest
Change amplificationWould a plausible small future change (a new field, a renamed concept) require edits in many places?
Cognitive loadHow much must a reader hold in their head to modify this safely: hidden ordering rules, flags, shared state, special cases?
Unknown unknownsIs 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>

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.