agentleFS
hudrazinehudrazine/velkross/skills/right-size-engineering/SKILL.md

right-size-engineering

Skill1 starsChanged 5 months agoMITView on GitHub

Calibrate software engineering decisions across macro, meso, and micro perspectives so the result is complete without unsupported structure, detail, or scope. Use when requirements, architecture, design, implementation, migration, or verification may be misaligned; when local and structural approaches compete; when a decision introduces enduring commitments; or when over- or under-engineering is a material risk. Avoid for fully specified mechanical work, unconstrained exploration with no decision to make, or tasks owned by a more specific review method.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 13 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    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:

    Use macro, meso, and micro as relative perspectives on the current subject, not fixed development phases:

    line 10
  2. Distinctive:

    Do not treat a perspective as a measure of importance, change size, or permission to expand scope.

    line 21
  3. Distinctive:

    Start at the perspective where the decision appears to belong.

    line 27
  4. Distinctive:

    look upward to justify purpose, scope, or enduring structure

    line 29
  5. Distinctive:

    look downward to confirm feasibility, behavior, failure semantics, or verification

    line 30
  6. Distinctive:

    Place the decision at the boundary that owns its consequences.

    line 31
  7. Distinctive:

    Do not perform a complete three-perspective analysis by default.

    line 34
  8. Distinctive:

    Stop traversing perspectives when the decision is supported at its owning level and its material adjacent consequences are accounted for.

    line 37
  9. Distinctive:

    Prefer a direct local solution when the responsibility is local.

    line 49
  10. Distinctive:

    Treat these as signs of over-engineering:

    line 55
  11. Distinctive:

    Treat these as signs of under-engineering:

    line 62
  12. Distinctive:

    Keep routine perspective analysis implicit.

    line 76
  13. Distinctive:

    Do not prescribe specialized requirements, architecture, boundary design, implementation, testing, security, performance, migration, or …

    line 86

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

Right-Size Engineering

Make the least speculative engineering commitment that completely supports the required outcome.

Use macro, meso, and micro as relative perspectives on the current subject, not fixed development phases:

  • Macro — purpose and system effect: outcome, users, contracts, constraints, non-goals, and consequences
  • Meso — structure and ownership: responsibilities, boundaries, relationships, workflows, dependency direction, and propagation
  • Micro — mechanism and evidence: behavior, state, algorithms, failure handling, configuration, tests, and operational details

A project, subsystem, module, API, or function can each be examined through all three perspectives. Do not treat a perspective as a measure of importance, change size, or permission to expand scope.

Calibrate The Decision

  1. Identify the required outcome, current decision, hard constraints, available evidence, and material uncertainty.
  2. Start at the perspective where the decision appears to belong.
  3. Inspect the nearest adjacent perspective when needed:
    • look upward to justify purpose, scope, or enduring structure
    • look downward to confirm feasibility, behavior, failure semantics, or verification
  4. Place the decision at the boundary that owns its consequences.
  5. Choose the least irreversible solution supported by present requirements and evidence.

Do not perform a complete three-perspective analysis by default. Traverse only far enough to resolve material uncertainty or detect a plausible mismatch.

Stop traversing perspectives when the decision is supported at its owning level and its material adjacent consequences are accounted for. Do not continue into hypothetical impacts.

Keep The Perspectives Aligned

Require:

  • an upper-level reason for every material lower-level commitment
  • a structural owner for every cross-cutting responsibility
  • a concrete mechanism and practical evidence for every claimed behavior
  • explicit deferral when current evidence does not justify a commitment

Prefer a direct local solution when the responsibility is local. Prefer a structural solution when local changes would duplicate policy, expose an ownership gap, or leave the required outcome incomplete.

Detect Misalignment

Treat these as signs of over-engineering:

  • a lower-level mechanism or abstraction lacks an upper-level requirement
  • a local problem is promoted into system-wide structure without evidence
  • optionality, configuration, extension points, or layers serve only hypothetical use
  • the solution commits more boundaries or concepts than the outcome requires

Treat these as signs of under-engineering:

  • an upper-level promise has no structural owner or concrete realization
  • a local solution leaves a known invariant, caller, workflow, or contract inconsistent
  • relevant failure, migration, compatibility, state, or operational effects are unowned
  • confidence depends on assumptions that practical verification could test

Expand, reduce, or defer the decision only in response to such evidence. Do not mistake more engineering for completeness or less engineering for simplicity.

Composition

Apply this calibration within the primary task and follow its workflow and output format.

Keep routine perspective analysis implicit. Do not produce a separate macro, meso, and micro report or label routine reasoning with these perspectives unless requested.

Surface a perspective mismatch only when it materially affects the outcome, scope, design, risk, assumptions, deferred work, or verification.

Keep The Responsibility Bounded

Own perspective selection, cross-perspective alignment, and over- or under-engineering checks.

Do not prescribe specialized requirements, architecture, boundary design, implementation, testing, security, performance, migration, or review methods. Apply relevant project or domain guidance separately when one becomes the primary task.

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.