agentic-dev/.claude/skills/evaluate-library/TRACE-TEMPLATE.md

# Trace Template

Use this file as the structural guide when writing a library decision trace. Copy the frontmatter block and all 11 headings. Replace placeholder values with real results.

Trace path: `docs/library-decisions/<YYYY-MM-DD>-<package-name>.md`

---

## Frontmatter — all filters evaluated

```markdown
---
package: <npm-package-name>
version: "<semver range>"
tier: app | feature | core
decision: approved | rejected
date: <YYYY-MM-DD>
deciders: [<author>, ...]
adr: adr-NNN | null
filter-results:
  license: <SPDX id>
  types: native | "@types/<x>" | none
  maintenance: active | dormant | abandoned
  boundary-fit: pass | fail
  shadow-check: pass | fail | "shadows <x>"
  eu-residency: ok | n/a | self-hostable | fail
  cve-scan: clean | "<advisory-id>" | fail
  named-consumer: pass | fail
  socketRisk: clean | flagged | <finding-summary>
verification-commands:
  - <literal command that produced the license result>
  - <literal command that confirmed types>
  - <literal command that checked maintenance>
  - <literal command that ran the CVE scan>
accepted-cves: []
---
```

## Frontmatter — partial trace (expensive filters short-circuited)

When an expensive filter fails (Phase 2 short-circuit), set remaining filter fields to `skip`. The Zod schema validates approved traces end-to-end; `skip` is the accepted sentinel for unevaluated fields in rejected traces.

Example: `maintenance: abandoned` → `cve-scan`, `eu-residency`, `named-consumer` skipped.

```markdown
---
package: <npm-package-name>
version: "<semver range>"
tier: feature | core
decision: rejected
date: <YYYY-MM-DD>
deciders: [<author>, ...]
adr: null
filter-results:
  license: MIT
  types: native
  maintenance: abandoned
  boundary-fit: pass
  shadow-check: pass
  eu-residency: skip
  cve-scan: skip
  named-consumer: skip
  socketRisk: skip
verification-commands:
  - npm view <pkg> time.modified
accepted-cves: []
---
```

---

## Required headings (11 total, in this order)

### Filter sections (8)

```markdown
## Filter: license

<!-- Result: <SPDX id> -->

Record the SPDX identifier from `package.json` or `npx license-checker --packages <pkg>`.
Allowed: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0.
Anything else → auto-reject (note the identifier and rejection reason).

## Filter: types

<!-- Result: native | @types/<x> | none -->

Confirm TypeScript types are available. `native` = ships its own `.d.ts`; `@types/<x>` = community
types package exists and is current; `none` = no types → auto-reject.

## Filter: maintenance

<!-- Result: active | dormant | abandoned -->

Check last release date and recent PR/issue activity. `active` = last release < 18 months AND
activity < 12 months. `dormant` = stable but not actively developed (acceptable for finished
libraries). `abandoned` = auto-reject.
If skipped (earlier expensive filter failed), write: "Not evaluated — skipped due to <filter> rejection."

## Filter: boundary-fit

<!-- Result: pass | fail -->

Confirm the dependency does not violate ESLint boundary-tag rules for the target tier
(ADR-006, ADR-010, ADR-017). Name the specific rule checked and the result.

## Filter: shadow-check

<!-- Result: pass | fail | "shadows <x>" -->

Check whether this library duplicates a must-have already locked in the workspace.
Locked must-haves: zod, inversify, payload, @trpc/server, superjson, reflect-metadata.
`shadows <x>` → auto-reject; a replacement requires a dedicated ADR.

## Filter: eu-residency

<!-- Result: ok | n/a | self-hostable | fail | skip -->

If the library transmits user data, telemetry, or business state to a vendor-controlled
endpoint by default, the vendor must offer an EU data region and the integration must be
configured to use it. Pure in-process libraries and build-time tools → `n/a`.
If skipped, write: "Not evaluated — skipped due to <filter> rejection."

## Filter: cve-scan

<!-- Result: clean | "<advisory-id>" | fail | skip -->

Run `pnpm audit --audit-level=moderate`. `clean` = no advisories at adoption time. Record
accepted advisory IDs in the `accepted-cves` frontmatter field and explain the risk acceptance
here. If skipped, write: "Not evaluated — skipped due to <filter> rejection."

## Filter: named-consumer

<!-- Result: pass | fail | skip -->

Answer: "Who calls this code path today, or who is blocked waiting for it?"
Hypothetical future callers are not consumers (ADR-022 §2.8 — the direct response to the
2026-05-14 OpenAPI near-miss). If skipped, write: "Not evaluated — skipped due to <filter> rejection."
```

### Prompt sections (3)

```markdown
## Prompt: replaces

<!-- Required: answer in either direction with justification -->

What existing library or approach does this replace? New-and-old running in parallel is a smell.
Name the thing being retired and its retirement plan, or explain why parallel adoption is
intentional and time-bounded.

## Prompt: migration-cost-out

<!-- Required: mechanical | hard | impossible + justification -->

What does ripping this back out look like 18 months from now? Rate: mechanical (swap package,
update call sites), hard (scattered integration, data-format dependencies), or impossible
(vendor lock-in, protocol coupling). Higher migration cost raises the adoption bar.

## Prompt: alternatives-considered

<!-- Required: minimum two named alternatives, or "none with explanation" -->

Name at least two alternatives evaluated before choosing this library. For core-tier adoptions,
this section is also duplicated into the companion ADR. If no alternatives exist, explain why.
```