# Engineering Research

> >

- **Type:** Skill
- **Install:** `agentstack add skill-adeerkhan-vitruvius-engineering-research`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [adeerkhan](https://agentstack.voostack.com/s/adeerkhan)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [adeerkhan](https://github.com/adeerkhan)
- **Source:** https://github.com/adeerkhan/vitruvius/tree/main/skills/engineering-research

## Install

```sh
agentstack add skill-adeerkhan-vitruvius-engineering-research
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
2. The question is stated specifically enough to derive a slug and evidence
   needs. If it is too vague, ask ONE clarifying question, then proceed.
3. The user's jurisdiction/edition context is known or the run will mark
   edition-sensitive claims `partial`.
4. 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](https://github.com/adeerkhan)
- **Source:** [adeerkhan/vitruvius](https://github.com/adeerkhan/vitruvius)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-adeerkhan-vitruvius-engineering-research
- Seller: https://agentstack.voostack.com/s/adeerkhan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.