agentleFS
joelaharris98joelaharris98/legal-ai-engineering-lab/.agents/skills/architecture-review/SKILL.md

architecture-review

Skill2 starsChanged 3 months agoMITView on GitHub

Automatically use when the project is becoming more structured or reusable — code is moving out of an experiment, a module/service/repository/interface/API/database/queue/framework is being considered, responsibilities feel tangled, duplication appears, the owner asks how something should be organised, or they ask whether to adopt a framework, a library, or a pattern they have seen elsewhere. Review architecture proportionately and explain every important recommendation in plain English. Do not use for a self-contained experiment that is not being reused, for routine edits within an existing structure, or merely because a file has grown long.

85 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-stories, story-done and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • lilangMaxSkill

    create-stories

    Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.

    Also in 11 projects that use this

  • lilangMaxSkill

    story-done

    End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint.

    Also in 11 projects that use this

  • +10 more from lilangMax

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 7 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 77 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not reward complexity for its own sake.

    line 13
  2. Distinctive:

    Start by explaining what the system currently does in plain English.

    line 15
  3. Distinctive:

    If the answer is mostly no, keep the code local.

    line 68
  4. Distinctive:

    When adding one, explain what the code looked like before, what pain actually appeared, and why the abstraction is now worth its cost.

    line 100
  5. Distinctive:

    Do not use it:

    line 140
  6. Distinctive:

    If a recommendation depends on an AI behaviour being good enough, invoke

    line 156
  7. Very specific:

    If the review introduces or changes data access, AI tools, permissions, external systems, confidential information, or consequential …

    line 159
  8. Very specific:

    If the review creates a meaningful reusable lesson, use learning-review after implementation or once the decision is concrete.

    line 160
  9. Very specific:

    If the architecture decision is now supported by real project evidence and would be useful externally, use interview-review at the next …

    line 161
  10. Distinctive:

    After the review, return to implementation.

    line 163

“Common” is measured: kept by at least 6 in 10 of the 77 edited versions of this file we could read. “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
<!-- Generated from ../../../.claude/skills/architecture-review/SKILL.md - do not edit this copy. Edit the source and run `uv run python scripts/sync_agent_files.py`. -->

Architecture Review

Review the current project as a senior legal-tech engineer and mentor.

Do not reward complexity for its own sake. The purpose is to make the system easier to understand, change, test, and trust—not to make it look more sophisticated.

Start by explaining what the system currently does in plain English.

Then assess, where relevant:

  • whether the architecture matches the actual maturity of the project;
  • whether responsibilities are separated for real reasons or merely by convention;
  • what should remain local to one experiment versus become reusable code;
  • whether deterministic logic and AI interpretation are separated sensibly;
  • whether model outputs are validated before other code trusts them;
  • whether source provenance is preserved where it matters;
  • whether the intended user could check the output more cheaply than doing the work by hand, and whether the structure makes that easy or hard to add later;
  • whether AI tools expose narrow capabilities rather than broad infrastructure access;
  • whether permissions and business rules are enforced outside the model;
  • whether consequential side effects have suitable human control;
  • whether important actions can be audited;
  • whether deterministic tests and AI evaluations match the real risks;
  • whether a dependency, framework, service, or abstraction is premature;
  • what would have to change before the project responsibly moves to the next maturity stage — docs/LEGAL_AI_DESIGN.md holds the production-readiness questions worth being able to answer at that point, which are questions to answer rather than infrastructure to build.

Where the project has grown enough for responsibilities to need separating, docs/LEGAL_AI_DESIGN.md sets out the four kinds — domain, application, infrastructure, interface — and why they change for different reasons.

Two tests before proposing a boundary

Both are quick, and both are things the owner can apply themselves afterwards, which makes them worth naming rather than just applying silently.

The deletion test. Imagine deleting the module and pasting its contents back into whatever calls it. If the complexity simply vanishes, the module was passing work through, and it was costing a layer of indirection to do so. If the same complexity reappears in three different callers, it was earning its keep. This is a sharper question than "is this file too long", and it answers the one that actually matters.

One caller is a guess; two is evidence. A boundary introduced for a second use that has not appeared yet is a guess about the future, and the guess is usually wrong in a detail that makes the boundary the wrong shape. Wait for the second caller. It is far cheaper to extract a module from working code than to reshape one built for an imagined use.

The three judgements this skill exists to make

Should this be a module?

A module represents a responsibility with its own reason to change, never a file that got long. Before proposing one, ask whether you can give the responsibility a precise name, whether it has a clear input and output, whether its rules could change independently of the surrounding code, whether it is worth testing separately, whether another workflow would plausibly reuse it, and whether extracting it makes the calling code easier to read. If the answer is mostly no, keep the code local.

Names carry most of the signal. documents, deadlines, chronology, matters, audit, tools all name a responsibility. helpers, utils, misc, and functions name nothing, and almost always mark a boundary drawn for convenience rather than meaning.

Should this be promoted out of an experiment?

Promotion into src/legal_lab/ is a decision, not something that happens because a file grew. Ask whether it will genuinely be used repeatedly, whether its purpose is now stable, whether the inputs and outputs are understood, whether failure matters enough to want tests, whether the concept is useful outside this one experiment, and whether the capability can be given a clear domain name.

An experiment becoming long is not a reason. Neither is it working well — see evaluation-review before promoting anything whose quality is still an impression.

Is this abstraction earning its cost?

Introduce a pattern when the problem it solves is visible, not because professional codebases contain it:

  • a reusable module, once behaviour is duplicated or changing for independent reasons;
  • a data-access boundary, once database details are leaking through business logic;
  • a way to make a repeated request harmless (idempotency), once a retry could do the same thing twice — a run that failed after writing the deadline, retried, writing it again;
  • background work, once something genuinely must happen outside the request;
  • a service boundary, once workflows have become hard to reason about.

Each of those is a past-tense condition. If it has not happened yet, the abstraction is a guess.

When adding one, explain what the code looked like before, what pain actually appeared, and why the abstraction is now worth its cost. That explanation is what makes the decision contestable later; without it, the structure becomes something nobody feels able to remove.

Complexity that is not earning its keep usually looks like one of these:

  • layers that merely pass arguments through;
  • interfaces with only speculative future implementations;
  • generic frameworks built before two real use cases exist;
  • distributed infrastructure, queues, or microservices for local work;
  • dependency-heavy agent frameworks wrapped around a single model call;
  • elaborate configuration for values that rarely change;
  • abstractions that are harder to explain than the code they replace.

Where simpler code is sufficient, prefer it and say why. Restraint is an engineering decision, and it is worth naming as one rather than leaving it to look like an omission.

Explain recommendations from the problem outward

For every material recommendation, explain:

  1. Practical problem — what concrete difficulty exists now?
  2. Recommended change — what would we alter?
  3. Why it helps — what becomes safer, simpler, clearer, or easier to change?
  4. Technical name — introduce the engineering term only if useful.
  5. Legal-tech relevance — why does this matter in systems lawyers rely on?
  6. Complexity introduced — what does this cost, and what is now harder?
  7. What would make us revisit it — the evidence or change that would reopen this.
  8. External explanation — how could the owner explain the decision in an interview?

Where there are several reasonable designs, present the meaningful options and trade-offs. Involve the owner in decisions that are valuable for them to reason about; do not make them approve trivial details.

Finish with the three highest-value improvements, ordered by impact rather than engineering fashion.

When not to use this skill

An unnecessary architecture review is not a free safety margin. It costs the owner's attention and pushes structure onto code that has not earned it, which is the exact failure this repository is trying to avoid.

Do not use it:

  • for a self-contained experiment that nothing else depends on, however long the file is;
  • because a file has grown — length alone is not a reason to create a module;
  • for routine edits that fit the structure already there;
  • to propose architecture for a problem the project does not yet have;
  • because a review has not run for a while. Elapsed time is not a trigger; a change in structure or maturity is.

Length is not tangling. The signal is that responsibilities have started changing for different reasons, or that a second caller now needs the same behaviour.

Handoff to other skills

Hand off to at most one of these, and note the rest rather than running them.

  • If a recommendation depends on an AI behaviour being good enough, invoke evaluation-review first: restructuring around an unmeasured capability builds on an assumption.
  • If the review introduces or changes data access, AI tools, permissions, external systems, confidential information, or consequential actions, invoke security-review before treating the design as safe enough to rely on.
  • If the review creates a meaningful reusable lesson, use learning-review after implementation or once the decision is concrete.
  • If the architecture decision is now supported by real project evidence and would be useful externally, use interview-review at the next meaningful milestone.

After the review, return to implementation. Re-run this skill when the project's structure or maturity changes again; do not turn it into a review required after every edit.

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.