chore(template): clean-slate template snapshot from bb4a0c7
Curated, product-agnostic snapshot of the post-story-04 tree: demo content deleted, auth-only reference feature, web-next shell, all gates green. Product-specific docs, ADRs 027-029, PRDs/epics/archive, editor library traces, and product naming are curated out; generic template repairs (coverage provider devDeps, root test:coverage script, live lint fixes, root-only release-please) are kept. See TEMPLATE.md for provenance, curation list, and usage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
This commit is contained in:
167
.claude/skills/evaluate-library/TRACE-TEMPLATE.md
Normal file
167
.claude/skills/evaluate-library/TRACE-TEMPLATE.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# 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.
|
||||
```
|
||||
Reference in New Issue
Block a user