1. Read the demo packet
Start with the public demo result and the proof upgrades page. The goal is to understand how TraceMap labels evidence, gaps, and public-safe summaries.
Adoption playbook
Introduce TraceMap as a review workflow, not a verdict machine.
This playbook gives engineering leads, reviewers, staff engineers, managers, and repository owners a bounded way to try deterministic static evidence before asking a team to change how it reviews code.
Public claim level: concept. No public conclusion without evidence. This page is process guidance for review conversations, not a product promise or replacement for engineering judgment.
Starting posture
Begin with a public packet before touching private code.
Demo firstRun or read the public demo and current demo result so the team sees the shape of generated summaries, proof paths, evidence tiers, coverage labels, counts, and limitations.
Public exampleThe first workflow pass should start with the public demo before any private repository scan enters the conversation.
Question firstName one review question and one repository owner before widening the scan scope. The first adoption pass should answer whether the evidence is useful, not whether the system is complete.
Boundaries firstReview validation and limitations before presenting results so partial coverage, syntax fallback, missing project load, and unsupported framework knowledge stay visible.
Owner firstEvery remaining question should land with the person or team that can inspect source, tests, telemetry, documentation, or future extractor work.
Workflow
Six adoption steps keep the first rollout small and inspectable.
2. Pick a candidate area
Choose one repository, service area, or review surface with a clear owner and a concrete static question, such as which routes, packages, config families, or database-facing surfaces are nearby.
3. Run a deterministic scan
Run TraceMap against a repository and commit SHA. Treat generated artifacts as evidence to inspect, not conclusions to accept blindly.
4. Read the evidence packet
Look for rule IDs, evidence tiers, file paths, line spans, commit SHA, extractor versions, coverage labels, and documented limitations when those details are available.
5. Make gaps explicit
Partial analysis is useful only when it is clearly labeled as partial. Reduced coverage, syntax fallback, unavailable project load, and owner-review rows should stay attached to the packet.
6. Assign follow-up
Route the remaining questions to repository owners, runtime owners, test owners, documentation owners, or future extractor work instead of asking static evidence to answer everything.
The first useful outcome is a better review question.
A successful adoption pass does not need to settle every dependency conversation. It should show whether a team can move from broad dependency worry to a smaller packet: the named surface, the static paths found, the evidence tier, the coverage label, the limitation, and the owner of the next check.
What TraceMap contributes
Static evidence gives the room a common object to inspect.
rule idWhich deterministic extractor or reducer rule produced the row?evidence tierIs the support semantic, structural, syntax/textual, or an explicit unknown?coverage labelIs this complete for the scanned scope, reduced, partial, or unavailable?proof pathWhere can a reviewer inspect the public-safe route, demo result, report family, or source-backed reference?limitationWhat does the packet not prove, and who owns that remaining review step?Boundaries
The playbook is not runtime proof or release approval.
- TraceMap organizes deterministic static evidence; it does not prove runtime behavior, production traffic, endpoint performance, outage cause, release safety, or operational safety.
- TraceMap does not replace CI/CD, tests, telemetry, ownership, human review, release approval, incident response, or governance.
- TraceMap should not say a change is affected unless reducer-backed public-safe evidence supports that wording.
- TraceMap concept pages describe how to work with evidence and gaps; they do not prove complete product coverage.
Public-safe material
Share the orientation layer, then keep private scans private.
Safe to summarizePublic routes, public demo summaries, sanitized labels, hashes, counts, rule IDs, evidence tiers, coverage labels, limitations, and reviewed proof paths.
Keep privateSource excerpts, database query text, configuration values, credentials, workstation paths, repository locations, scan folders, private sample identities, local fact streams, local indexes, and analyzer diagnostics.
Review before publishingPrivate repository evidence needs a human-cleared public-safe summary before it becomes site copy, meeting material, or broad stakeholder communication.
Next routes