agentleFS
wheeloswheelos/apollo-lite/.agents/skills/engineering-solution-design/SKILL.md

engineering-solution-design

Skill177 starsChanged 7 days agoApache-2.0View on GitHub

Design engineering solutions through industry practices, open-source research, reuse-versus-build comparison, and architecture decisions. Use for technology selection, solution comparison, open-source adoption, engineering patterns, architecture, and minimal framework design.

The file

Show its rules and text

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈22

    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 for designing new capabilities, technology selection, architecture evolution, and adopting engineering patterns from open-source …

    line 10
  2. Distinctive:

    When an existing solution meets the needs of a clearly scoped small change, reuse it and record only new constraints and necessary …

    line 26
  3. Distinctive:

    Follow the repository's agent rules and read relevant source, tests, and necessary context for the target module.

    line 32
  4. Distinctive:

    Ask first when missing information could change the selection, system boundary, or key behavior.

    line 38
  5. Distinctive:

    Use only public, non-sensitive questions for external research.

    line 40
  6. Distinctive:

    Look for existing answers first: Prefer verified implementations, interfaces, and engineering patterns for mature, general problems.

    line 45
  7. Distinctive:

    Match depth to risk: Use brief comparisons for simple, reversible decisions and stronger evidence for costly, irreversible, or high-risk …

    line 61
  8. Distinctive:

    Use blogs and rankings only to discover leads.

    line 91
  9. Distinctive:

    Start with a small set of candidates and usually compare two or three representative options in depth.

    line 93
  10. Distinctive:

    Check licenses, transitive dependencies, and distribution obligations.

    line 115
  11. Distinctive:

    Do not generalize findings about one version into claims that apply to the project forever.

    line 117
  12. Distinctive:

    Use dimensions relevant to the task.

    line 127
  13. Distinctive:

    Use weighted scores only when weights and scoring criteria are clear.

    line 137
  14. Distinctive:

    When evidence is insufficient, provide a conditional recommendation and minimal validation plan.

    line 142
  15. Distinctive:

    Do not label a risk that determines whether the solution is viable as an unrelated detail.

    line 177
  16. Distinctive:

    If the user requests only framework design, deliver module boundaries, key contracts, and implementation order.

    line 194
  17. Distinctive:

    If implementation is authorized, prioritize completing this path and reuse existing engineering and test mechanisms:

    line 196
  18. Distinctive:

    Use representative loads and a baseline to validate specific risk hypotheses.

    line 203
  19. Distinctive:

    Run only the minimum validation needed to cover the change, using repository-verified commands and environments.

    line 205
  20. Distinctive:

    Only authorized code, dependencies, and persistent documents are changed.

    line 243
  21. Distinctive:

    If an external source is unavailable, use accessible public primary sources or existing versioned evidence.

    line 247
  22. Distinctive:

    Stop the affected work when constraints conflict, a key experiment fails, or a significant trade-off remains.

    line 251

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

Engineering Solution Selection and Design

Scope

Use for designing new capabilities, technology selection, architecture evolution, and adopting engineering patterns from open-source projects. The goal is a minimal, correct solution that is evidence-based, trade-off aware, and implementable in stages—not a collection of technology buzzwords. The default deliverable is a design; modify code or build a framework only when implementation is explicitly part of the task.

Task routing

This skill addresses what to select, why, and where to draw boundaries; it does not take over algorithm implementation or fault investigation. Hand off algorithm implementation to algorithm-development, unknown anomalies to issue-localization, resource bottlenecks to performance-optimization, and scenario validation to simulation-regression. See the skill index for entry points and method references. Hand off only when needed for the current task. When an existing solution meets the needs of a clearly scoped small change, reuse it and record only new constraints and necessary trade-offs; do not require a new candidate matrix, document, or approval process.

Prerequisites

  • Follow the repository's agent rules and read relevant source, tests, and necessary context for the target module.
  • Confirm existing capabilities, module ownership, dependency boundaries, and worktree changes; prefer reusing existing repository mechanisms.
  • Clarify goals, non-goals, use cases, delivery stages, and non-negotiable constraints.
  • Ask first when missing information could change the selection, system boundary, or key behavior; explicitly label other assumptions.
  • Use only public, non-sensitive questions for external research. Do not upload internal code, logs, credentials, or business data.

Core principles

  • Look for existing answers first. Prefer verified implementations, interfaces, and engineering patterns for mature, general problems. Do not reinvent them to demonstrate design skills, and do not copy an entire architecture just because a project is well known.
  • Adopt mechanisms, not scale. Distinguish direct dependencies, protocol compatibility, local adaptation, conceptual borrowing, forks, and in-house development. Each has different licensing, maintenance, and upgrade costs.
  • For unknown problems, establish principles first. For niche, unresolved, or highly customized problems, define invariants and trade-offs before deciding system boundaries, module responsibilities, and key contracts; address algorithm and implementation details last.
  • Prefer a working framework, not an empty shell. Some local details may be deferred, but do not skip feasibility risks that affect the architecture or substitute empty methods, swallowed errors, or false success for a working minimal path.
  • Match depth to risk. Use brief comparisons for simple, reversible decisions and stronger evidence for costly, irreversible, or high-risk decisions. Stop researching once the decision is supported; do not aim to exhaustively list projects.

Workflow

1. Define the problem and selection criteria

Briefly state business goals, the current baseline, inputs and outputs, non-goals, and success criteria. Separate hard constraints from tradeable requirements. Performance requirements should include the scenario, scale, and evaluation method; do not invent metrics.

First classify the problem, assessing modules separately when necessary:

Problem typeDefault path
Mature, general problemFind established patterns and implementations; compare reuse options and satisfy constraints with minimal adaptation
Mature core with a customized boundaryReuse the general core, isolate customized policies, and define interface and upgrade boundaries
Niche, unresolved, or highly customized problemConduct focused research, establish principles, design a framework, and validate key assumptions with risk experiments

“Not found yet” does not mean “does not exist in the industry.” State the research scope and missing evidence; do not claim that no solution exists.

2. Research established practices and open-source implementations

Gather evidence from official documentation, original papers or standards, project source, tests, release records, and maintainer discussions. Use blogs and rankings only to discover leads; stars, badges, and vendor claims alone do not demonstrate suitability. Start with a small set of candidates and usually compare two or three representative options in depth. State when evidence is insufficient; do not invent candidates to fill a quota. Include the existing implementation or adding no dependency as a baseline.

For candidates that affect the conclusion, inspect actual critical paths and representative tests, not only the README. Record source links, access date, and version or commit. For source evidence, use version-pinned paths and symbols, adding reliable line numbers when available. Distinguish:

  • Verified facts: What the source actually demonstrates; source code being present does not mean it has been run and validated.
  • Applicability assessment: Which scenarios match this project and which assumptions differ.
  • Unverified assumptions: Capabilities, costs, or limitations that still require an experiment or user confirmation.

For each reference project, state which mechanism is borrowed, what problem it solves, what is not adopted, and what adaptation is required. Compare total costs, including integration, deployment, debugging, long-term maintenance, upstream upgrades, fork patches, and replacement. Check licenses, transitive dependencies, and distribution obligations. Do not assume code may be copied when its license is unclear. Do not generalize findings about one version into claims that apply to the project forever.

3. Compare options and make a selection

Filter against hard constraints first, then weigh trade-offs. Eliminate options that fail a hard constraint. If a hard constraint is unknown, treat the option only as conditional; other advantages cannot “average out” the uncertainty.

Use dimensions relevant to the task; avoid an unnecessarily large comparison table:

Candidate and reuse approachEvidence and applicable scenariosHard constraintsEngineering and maintenance costsRisks/unknownsConclusion
Existing baselineActual behavior and shortcomingsMet/not met/unknownCost of keeping the status quoMissing evidenceRetain/reject and why
CandidateSource, version, and key mechanismMet/not met/unknownIntegration, upgrade, and exit costsValidation methodRecommend/alternate/reject and why

Compare direct reuse, thin adaptation, and in-house development when relevant, but do not require every task to include all approaches. Use weighted scores only when weights and scoring criteria are clear; do not use fabricated precision to disguise judgment.

State the recommended option, key reasons for rejecting alternatives, accepted disadvantages, and conditions that would trigger reassessment. When evidence is insufficient, provide a conditional recommendation and minimal validation plan; do not present selection as complete. Obtain necessary confirmation before implementing significant behavioral trade-offs or changes to dependencies, environments, or deployment.

4. Establish principles, then refine the architecture in layers

For customized parts, first write a small number of verifiable principles. Each principle should include an invariant, rationale, design impact, and verification method. Principles must constrain the design; avoid vague slogans such as “high performance” or “high extensibility.” For mature solutions, also state whether they are compatible with these principles.

Develop the design in the following order, going only as deep as the current decision requires:

  1. System boundaries: Users, external systems, trust boundaries, inputs and outputs, and deployment constraints.
  2. High-level structure: Main data and control flows, state ownership, dependency direction, and failure paths.
  3. Modules: Single responsibilities, interface contracts, state ownership, reuse sources, and customization boundaries.
  4. Key details: Expand only details that affect correctness, feasibility, performance thresholds, or compatibility.

At minimum, contracts must specify input/output semantics and error behavior; add timing, units, coordinate frames, concurrency, and lifecycle details as needed. Do not directly import another project's deployment scale or dependency ecosystem into this project. A simple diagram and a necessary module table are sufficient; do not require filling out an entire architecture-document template.

Classify unresolved details as “must validate first” or “can defer,” and state the reason for deferral, constraint boundary, and revisit conditions. Do not label a risk that determines whether the solution is viable as an unrelated detail. For autonomous-driving modules, specify coordinate-transform direction, time basis, data freshness, reset and relocalization behavior, real-time budgets, and failure/degradation contracts as applicable; do not assume every module needs every concept.

5. Plan a minimal end-to-end path and evolution

First define a minimal vertical path from input to an observable result rather than building every module at once. Typical stages are a critical-risk experiment, a minimal end-to-end path, and capability additions driven by need; do not mechanically require a fixed number of stages. For each stage, state deliverables, dependencies, acceptance criteria, and stop or rollback conditions.

If the user requests only framework design, deliver module boundaries, key contracts, and implementation order. If implementation is authorized, prioritize completing this path and reuse existing engineering and test mechanisms:

  • Report unimplemented capabilities explicitly; do not return fabricated success results.
  • State the scope of mocks, stubs, and diagnostic inputs; they are not evidence of production correctness.
  • Use representative loads and a baseline to validate specific risk hypotheses; do not report a plan as a measurement.
  • Run only the minimum validation needed to cover the change, using repository-verified commands and environments.
  • Identify which known changes motivate extension points; do not prebuild a generic plugin platform or unnecessary abstraction layers.
  • Limit handoff information to the selected solution, constraints, key contracts, unresolved risks, and acceptance criteria. Do not require the next stage to repeat research that is complete and still valid.

Deliverable format

Scale the following content to the problem; a few paragraphs are sufficient for small problems, and creating a document is not mandatory:

  1. Conclusion: Recommended approach, applicable assumptions, and selection status (proposed, pending validation, or confirmed).
  2. Constraints and principles: Goals, non-goals, hard gates, and design invariants.
  3. Evidence and comparison: Sources, candidates, scope of reuse, trade-offs, and reasons for rejection.
  4. Framework and modules: Critical path, ownership, interfaces, failure behavior, and deferred details.
  5. Implementation path: Minimal end-to-end path, acceptance criteria, risk experiments, exit conditions, and reassessment conditions.

For significant decisions, record context, drivers, options, decisions, consequences, and confirmation in an ADR-like format; do not create a separate ADR for every local implementation choice. Persist knowledge only when requested by the user, following the maintenance rules for ad_agents/context/ and updating its index. Do not establish a competing knowledge authority.

Acceptance

  • The recommendation has traceable evidence and identifies what does and does not match this project.
  • The comparison includes a viable baseline; rejected options have reasons; unknowns are not presented as facts.
  • A customized solution defines principles, boundaries, state ownership, key contracts, and a minimal end-to-end path.
  • Deferred details do not undermine the current architecture; key risks have validation and revisit conditions.
  • A design deliverable does not claim implementation was validated; an implementation deliverable does not treat a shell as complete.
  • Only authorized code, dependencies, and persistent documents are changed.

Failure handling

If an external source is unavailable, use accessible public primary sources or existing versioned evidence; do not bypass access restrictions or fabricate citations. If key evidence is still missing, lower confidence and state the gap. Stop the affected work when constraints conflict, a key experiment fails, or a significant trade-off remains. Explain the reason and options, then ask the user to decide; do not silently relax gates, introduce dependencies, or expand scope.

Method references

The following references provide methods, not fixed technology selections for all projects. Links are pinned to the reviewed versions. This workflow synthesizes them for the task; it does not require copying any template in full.

  • MADR decision template: context, drivers, candidates, consequences, and confirmation for traceable selection records.
  • arc42 architecture template: goals, constraints, context, strategy, building blocks, runtime views, quality, and risks for organizing a layered design.
  • OpenSSF Best Practices: licensing, release, testing, and maintenance practices for open-source projects; a self-certified badge is only a lead, not a substitute for validating suitability.

Sources last reviewed: 2026-10-26.

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.