Engineering Research

Engineering Research

Run the Vitruvius research loop for an engineering question or artifact. The discipline skill that dispatched here adds the evidence landscape and verification criteria; this skill is the method itself. It applies to all five disciplines unchanged.

Invocation Flags

/engineering-research  [--deep | --quick]

• --deep: Force multi-agent mode. Spawns researcher subagents regardless of query complexity. Uses parallel verification lanes for all claims. Use when the user wants comprehensive coverage or the topic is safety-critical.
• --quick: Force direct search mode. No subagents, no parallel verification. Lead agent searches and synthesizes alone. Use for simple lookups or when token cost matters.
• No flag: Auto-scale based on query complexity (default behavior — see Step 2 Scale).

Discipline skills pass these flags through to this method.

Tool Discipline (Read First)

• Use only tool names visible in the current tool set. If a tool returns "not

found", do not retry the same invalid call — map to a canonical visible tool or record the capability as blocked.

• Prefer official standards portals, code body text, primary vendor

documentation, and primary data over secondary summaries.

• When a source is paywalled or unreachable, cite it from search metadata and

mark full-text access as blocked instead of guessing at its contents. See references/blocked-access-policy.md for the full rules.

• To ask the user a question, write plain chat text and wait. Do not invent

tool names for asking questions.

This is an execution request, not a request to explain the workflow. Execute it. Do not answer by describing the protocol. Your first actions should be tool calls that create the plan artifact.

Context Management

Write research notes to disk after each search batch (extract findings to outputs/.drafts/-research-.md, don't accumulate in working memory). Bounded searches: 3–5 queries per phase, then extract to disk and re-search; 3 failed queries = mark blocked. Re-read plans and notes after interruption. Full practice: references/context-management.md.

Required Artifacts

Derive a short slug from the topic: lowercase, hyphenated, no filler words, at most 5 words (e.g. steel-brace-connection). Every run must leave files on disk:

• outputs/.plans/.md
• outputs/.drafts/-draft.md
• outputs/.drafts/-cited.md
• outputs/.md or papers/.md
• outputs/-problem-anchor.json (beside the candidate, not in a drafts dir)
• outputs/.provenance.md or papers/.provenance.md

File Write Fallback

The host must permit file writes for artifacts to persist. If a write fails:

1. Return the plan/draft/provenance content directly in the chat response
2. Continue the research loop — do not abort
3. Note in the final response that artifacts were not persisted to disk

Research content is valuable even without persistent artifacts. Never fail a research task solely because file writes are not permitted.

Intermediate research goes to -research-.md in the working directory or outputs/.drafts/. Never use generic names like research.md or brief.md. Concurrent runs must not collide.

After the user approves the plan, if any capability fails, continue in degraded mode and still write a blocked or partial final output and provenance sidecar. Never end with chat-only output after plan approval.

Step 1: Plan

Input Gate (all must hold before proceeding)

1. The request is a research question, artifact review, or verification task —

not routine coding, a direct design request, or an inline calculation the user wants performed.

1. The question is stated specifically enough to derive a slug and evidence

needs. If it is too vague, ask ONE clarifying question, then proceed.

1. The user's jurisdiction/edition context is known or the run will mark

edition-sensitive claims partial.

1. File writes are available OR the File Write Fallback below is acceptable.

If any gate fails, resolve it before writing the plan. Do not silently degrade — note the gate resolution in the plan's Decision log.

Problem anchor (freeze before searching)

Before any search, name what the report is about, not just what it will look up. Write these into the plan and keep them stable for the whole run:

• Artifacts under study — the files, repos, or documents this run is

actually about, with the commit or revision that pins them. A run with no artifact is a literature review; say so in the plan rather than implying a codebase was read.

• Decisions to inform — the 2-5 concrete decisions the reader will make

with this report (ship / defer / profile / measure / policy). Research that cannot name them is scope drift, and the goal-checker will catch it.

• Non-goals — what this run will not settle (usually product policy and

jurisdiction choice).

These three become the decisions and artifacts of the machine record in references/problem-anchor-contract.md, which is written beside the candidate and validated with vitruvius-problem-anchor. Anchors are resolved against real bytes, so a repo claim that does not match the snapshot fails closed instead of reaching review.

Create outputs/.plans/.md immediately. The plan must include:

• Key questions
• Problem anchor: artifacts under study (+ commit), decisions to inform, non-goals
• Evidence needed (standards, code provisions, vendor docs, datasheets, prior

designs, repos, prior art)

• Scale decision (below)
• Task ledger
• Verification log
• Decision log

Make the scale decision before assigning owners. If the topic is a narrow "what is X" explainer, the plan must use lead-owned direct search tasks only; do not allocate researcher subagents.

After writing the plan, proceed immediately to Step 2. Do not stop for confirmation — the plan is written to disk for the user to review, but the research loop continues without blocking.

Step 2: Scale

Use direct search for:

• Single fact or narrow question, including "what is X" explainers
• Work you can answer with 3–10 tool calls

For "what is X" explainer topics, do NOT spawn researcher subagents unless the user explicitly asks for comprehensive coverage or a broad survey. Do not inflate a simple explainer into a multi-agent survey.

Use subagents only when decomposition clearly helps:

• Direct comparison of 2–3 items: 2 researcher subagents
• Broad survey or multi-faceted question: 3–4 researcher subagents
• Complex multi-domain research: 4–6 researcher subagents

Parallel Fan-Out (T2)

Run independent skills simultaneously and merge when both complete — for example gap analysis with evidence ranking, several researcher subagents on different topics, or discipline skills on different domains. Gaps then inform evidence priorities. Do not parallelize sequential dependencies (the verifier needs the evidence first), skills that share state or context, or work constrained by the token budget.

Step 3: Gather Evidence

Increment Checklist (complete before moving to Step 4)

• [ ] At least 3 distinct search queries run
• [ ] At least 5 sources found and evaluated
• [ ] At least 2 source tiers represented (Tier 1-2 preferred)
• [ ] All numeric claims have units and sign conventions
• [ ] All standard citations include section + edition
• [ ] No sources appear AI-generated or undated
• [ ] Search terms recorded in research notes

If any checkbox is unchecked, continue searching before drafting.

If direct search was chosen:

• Skip researcher spawning entirely.
• Search and fetch sources yourself.
• Use multiple search terms/angles before drafting. Minimum: 3 distinct

queries for direct-mode research.

• When the question is scholarly (papers, prior art, standards research),

use the /skill:scholarly-research discovery layers: OpenAlex first (keyless REST), then Semantic Scholar / arXiv / alphaXiv fast search, and the host's own web or browser tools when visible.

• Record the exact search terms used and write notes to

outputs/.drafts/-research-direct.md.

• Continue to synthesis.

If subagents were chosen:

• Write a per-researcher brief first (e.g. outputs/.plans/-T1.md).

Researcher subagents are dispatched from the canonical role definition in agents/researcher.md; they write findings to their output file and return a one-line summary.

• Keep tool-call JSON small and valid; do not place multi-paragraph

instructions inside the subagent JSON.

• Always set failFast: false.
• Do not name exact tool commands in subagent tasks unless those tool names

are visible in the current tool set. Prefer broad guidance: "use standards search and web search".

• Prefer file-based handoffs: the researcher writes findings to its output

file and returns a one-line summary; the lead reads the file.

Evidence-gathering rules (researcher role): the six integrity commandments in AGENTS.md are non-negotiable here. In brief — never fabricate a source, never claim something exists without checking it, never describe a source you have not read, give a checkable locator for every entry, read before you summarize, and mark status honestly.

Source quality: prefer official standards bodies, code text, primary vendor documentation, datasheets, peer-reviewed engineering literature, and reputable government/industry sources. Accept with caveats well-cited secondary sources and established trade publications. Deprioritize undated blog posts, content aggregators, primary-less forum posts, and SEO listicles. Reject anything with no author and no date, or that appears AI-generated with no primary backing.

Evidence table format — assign each source a stable numeric ID for downstream traceability:

| # | Source | Reference (std+sec / URL / path) | Key claim | Type | Status | |---|--------|----------------------------------|-----------|------|--------| | 1 | ASME B31.3 | §304.1.2 | min wall thickness formula | code | verified | | 2 | this repo | packages/solver/src/x.ts:42 | treemap fills the host exactly | repo | verified |

Type is code, standard, paper, vendor, or repo. A repo row is a claim about the artifact under study, so it must carry a path:line anchor that resolves on disk. Never assert what a codebase does, lacks, or needs without opening it — the most expensive research failure is a confident finding about code nobody read. Full anchor rules: references/problem-anchor-contract.md.

Write findings with inline source references [1], [2]. Label inferences as inferences in the prose. End with a numbered Sources section matching the table.

Step 4: Draft

Write the brief yourself. Do not delegate synthesis.

Save to outputs/.drafts/-draft.md. Include:

• Executive summary
• Findings organized by question/theme
• Evidence-backed caveats and disagreements
• Open questions
• No invented sources, numbers, figures, tables, or claims

Every finding carries an ID, a type, and a changes line naming its landing site: change, measure, defer, product-decision, or background. This is what separates an engineering report from a survey. A finding with no landing site is either background or a product decision, and must say which. A finding that recommends building something must first show it is absent — with an anchor, not an assertion.

Two sections are mandatory, not optional:

• ## What we did not find — what you searched for, did not find, and the

boundary of the search. Silence reads as "no problems exist"; this section makes the gap itself evidence.

• ## Impact vs. evidence — for each recommendation, the evidence behind

it and the cost of being wrong. An unsupported priority ranking is a guess wearing a table.

Then write the vitruvius-problem-anchor.v1 record beside the candidate from references/problem-anchor-contract.md and run vitruvius-problem-anchor (or node scripts/problem-anchor-contract.mjs in a checkout). It must pass before the brief moves to verification: every decision reached a position, every repo anchor resolves to a non-blank line on disk, and the candidate actually cites them. Repair a failed record by fixing the claim or the anchor — never by deleting the finding.

Before citation, sweep the draft: every critical claim, number, figure, or table must map to a source reference, research note, raw artifact path, or calculation. Remove or downgrade unsupported claims. Mark inferences as inferences. A numeric claim without a unit, sign convention, and source is not a claim — it is noise. Flag it.

Step 5: Verify (Blind Verifier)

After the cited brief exists, run the Blind Verifier as a subagent with FRESH context. This is mandatory for all non-trivial research. The role's canonical definition is agents/verifier.md — dispatch it with that file's content as the subagent prompt. The verifier receives:

• The research question
• The gathered evidence (with source locations)
• The claimed conclusion

It does NOT receive your reasoning chain — that separation is the point. It must have NO write/edit capability: the verifier reports, it never repairs. It returns PASS / PARTIAL / BLOCKED with an evidence trail and default-FAIL posture (it actively looks for flaws).

If the verifier returns BLOCKED, fix the fatal issues and re-run. If PARTIAL, note the qualifications in Open Questions. Do not run the verifier and any reviewer in the same parallel subagent call — verify first, then review.

Conditional Escalation (A4 — from Autoprompt L4 pattern)

Verification escalates based on claim criticality and verifier disagreement. Keep the flat agent structure — escalation is conditional, not hierarchical.

Escalation Rules

| Scenario | Action | Agents | |----------|--------|--------| | Routine claim (informational) | Single verifier | 1 | | Critical claim (safety, code-backed, structural) | Parallel verify | 2 | | Verifiers disagree (different verdicts) | Escalate to arbiter | 3 | | All three disagree | BLOCKED, document disagreement | — |

When to Use 2 or 3 Verifiers

Use 2 verifiers when --deep is set, when the claim involves life-safety (structural, fire, electrical, pressure vessels), when a specific code provision is the sole basis, when a numerical result governs a design decision, or when the claim spans multiple engineering fields. Escalate to 3 when the first two return different verdicts, when a safety-critical claim carries high stakes of being wrong, or when the evidence is ambiguous or conflicting.

Arbiter and independence

The arbiter is dispatched from agents/arbiter.md with the original question, the evidence, the two prior verdicts and their evidence trails, and the instruction: "Two verifiers disagree. Review both trails and render a majority verdict." It does NOT re-research — it adjudicates between the two existing verdicts. Majority wins; all three disagree returns BLOCKED with documentation.

Documenting Disagreement and Independence

When verifiers disagree, the provenance sidecar records one ## Verifier Disagreement block: each verdict and reason, the arbiter's verdict and reason, and the resolution. A disagreement with no recorded resolution is an open finding, not a closed one.

Every verifier/reviewer MUST be a fresh subagent instance; no agent reviews work it authored; concurrent verifiers share no verdict channel; negative verdicts loop back to the lead agent, never sideways. For routine (informational, non-safety) claims a single verifier is sufficient.

Step 6: Review

After the verifier passes, do a final self-review: check that all PARTIAL qualifications are noted in Open Questions, all FATAL issues are fixed, and the provenance sidecar is complete.

Step 6.5: Post-Edit Verification Audit (MANDATORY)

After the verifier passes and before delivery, run an adversarial citation audit. THIS STEP IS MANDATORY — do not

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adeerkhan
• Source: adeerkhan/vitruvius
• License: MIT

Install and usage instructions live in the source repository linked above.