---
name: roam-product-writing
description: "Draft, review, and improve Roam positioning and product copy across its website, README, offers, setup explanations, package descriptions, and metadata. Make its agent-first mechanical capabilities clear, useful, and persuasive without narrowing the product or overstating evidence. Not for unrelated products or CLI output schemas."
---

# Roam product writing

Explain why Roam belongs in a coding agent's tools, not just what features it
contains. An accurate sentence can still present the wrong product. Earn a
strong claim with concrete work and a supported mechanism, not adjectives.

Choose by the passage's job, not its file extension. Product explanation belongs
here; technical instructions for an acting agent need instruction/contract review,
and a new comparative benefit claim needs qualified measurement. A mixed page
can need both kinds of work without turning its explanation into an operating manual.

## Establish meaning and authority

Read [the source map](references/source-map.md) and the sources relevant to the
surface. Resolve the Roam checkout from context; a supplied frozen source packet
can replace repository reads in isolated trials. Treat current copy as editing
input, not its own factual proof. Cite source locations in separate working notes.

Latest explicit owner direction sets positioning; verified implementation bounds
capability; adopted records govern commercial terms. Older headlines are not
templates to restore. Distinguish working-tree, published, planned, and measured
behavior. Name a contradiction or unavailable fact; do not silently select the
convenient source. Keep private strategy and customer information out of public copy.
Package descriptions and registry cards are public copy too; a bounded website
claim does not repair an absolute claim in metadata.

Match evidence to the claim: implementation supports capability, the license
supports licensing, owner decisions govern offers, and measurements support
outcome comparisons. Missing one source is a specific gap, not grounds to
reject every supported part of a sentence.

Use the orientation's **The product model behind the words** as the maintained
meaning, not a stock tagline. Roam gives coding agents callable local analysis
and mechanical checks for investigating code, evaluating implementation choices,
and checking changes. Context, findings, algorithmic alternatives and scoped
verification evidence are useful outputs, not competing definitions of the product.
Some evidence comes from fixed experiments or replay, not just the code graph.
Do not reduce Roam to code understanding, a bug finder, or a post-edit reviewer.
The public atlas is an illustration for visitors, not the agent's working interface.

People choose tools and set direction; agents consume results. Generated code can
outpace line-by-line attention. Roam's value is making useful repository questions
mechanically answerable and repeatable, not declaring human reading obsolete or
the model incapable. Do not advertise a self-improving system or perfect understanding.
The agent reasons about applicability and directs work; Roam returns observations
and performs supported requested operations. Candidate improvements are not
implemented solutions or demonstrated speedups.

For substantive positioning work, first record a short private meaning brief:
the reader and their task, what Roam supplies, what the agent does with it, why
the mechanism is worth adding, and which evidence bounds the claim. This is
reasoning input, not a template to paste into every surface. Reading the docs is
not proof of understanding: check a mechanism beyond the opening example and
ask what remains useful when no defect is found. Resolve conflicting current
guidance rather than allowing the next page to inherit the same contradiction.

## Build a useful explanation

Identify the reader's question and the section's job before drafting. For an
opening, make the purpose recognizable and show why the supplied context/checks
matter to real work. For a capability card, connect a named output to its use.
For a FAQ, answer the practical objection and provide the next step.

In an opening, answer the reason to add Roam to an agent the reader already
uses. A category plus a feature list is not that answer. Explain useful work
and the mechanism that supplies it: query code relationships, inspect a pattern
and a candidate alternative, or obtain a recorded check result. Ready-to-query
analysis and executable checks let an agent consult results instead of deriving
each relationship or building each check anew. This is a mechanism, not a
measured saving or a claim that the existing agent cannot investigate code.
Choose a hook suited to the reader; neither a fixed verb trio nor one concrete
example should become the entire product identity.

Test the opening by paraphrasing only its visible words: what Roam supplies,
how it obtains that result, and what the existing agent can do with it. A list
of agent jobs (understand, find problems, improve, check) does not explain the
added tool. If the same opening could describe the coding agent itself, name
Roam's contribution instead of adding another benefit verb. This is a test of
the explanation, not a requirement for a unique competitive feature or a fixed
slogan. The headline sets the category or useful task; the lede must supply
the reason to add Roam without relying on a diagram or lower section.

Explain labels such as "context" through a useful output and next action.
Check a healthy-code case: what useful answer remains when no problem is found?
Reuse means an index or checked observation can serve later
questions under refresh conditions, not measured savings or automatic freshness.
Put refresh instructions in the workflow unless the opening implies reuse
across changed source; qualify that stronger claim immediately. Do not spend
every opening on setup.

Prefer files, functions, connections, duplicate code, tests, and checks to an
unexplained catalogue of technical categories. Keep necessary technical meaning.
When shortening, preserve a named output and how Roam obtains it. "Engineering
checks" or "candidate algorithms" alone can still hide the work: indexed callers,
a detected source pattern paired with a catalogued alternative, or a replay
result are more concrete when supported by the relevant source. Describe the
producer accurately rather than implying model-generated proposals. For an
adoption introduction, make the local, model-free nature of static checks
legible; "mechanical" is not a substitute for explaining it. Keep connected-model
usage separate. These are meaning checks, not required phrases in every section.
Use confident verbs for supported behavior and conditional wording for uncertain
inferences. Do not hedge every sentence. Stronger copy adds a specific result,
use, or mechanism; it does not need a larger promise. "Local graph + judgment +
evidence" may name internal concepts but does not explain a benefit to a visitor.
"Deterministic facts, not guesses" confuses repeatable analysis with certainty.

Read entry copy aloud as if explaining Roam to a developer over a desk.
Replace internal labels with the work they describe: a reader should not need
to decode “clone evidence” to learn that similar code may need attention.
Let the headline establish a recognizable category or invite a concrete task,
and let the lede explain the mechanism;
neither has to carry the whole product manual. Keep precise terms in technical
references where the audience needs them.
Use a nearby, clearly labelled example to show a useful question and returned
result; a list of check categories cannot do that job. Name what a broad phrase
such as “structural concerns” means in that example. Preserve the stronger
baseline passage when a warmer rewrite obscures the agent's next action.

Keep the actor clear in every instruction: is a person connecting the tools,
the agent consulting them, or Roam returning a result? Do not turn the agent-first
story into a list of manual chores. Give adjacent sections different explanatory
jobs; consistency is shared meaning, not repeating the same words everywhere.
An algorithm page can focus on candidate alternatives; a README introduction
needs the wider purpose; a paid offer sells its actual deliverable, not free
tooling relabelled as a subscription. Lead with useful work, attach the relevant
limit, and preserve agreed commercial terms. A focused page need not repeat the
whole capability range to be consistent.

## Keep essential boundaries attached

- Static checks use local compute without model calls. Free CLI/MCP tooling
  does not make the agent's model usage free or every optional feature offline.
- Ordinary analysis does not automatically upload source or telemetry. Parser
  downloads, selected online features, and connected-agent providers have their
  own data paths. Link the network boundary where relevant.
- An index requires refresh as code changes. Connection exposes tools; routine
  use requires workflow integration and is not enforced by installation alone.
- Findings are leads, incomplete observations stay incomplete, and suggested
  tests are not executed tests or coverage. Give a useful next action within
  the observed scope; do not erase valid evidence just because it is partial.
- Records capture configured evidence, not complete coverage, authenticated
  actor identity, or permission to ship. People retain intent and acceptance.
- Preserve current offers, prices, and terms. Planned capabilities and historical
  scenarios are not available products. No new speed, savings, adoption, or
  superiority claim without evidence appropriate to that claim.

A short section need not repeat the whole list. A qualification belongs beside
the claim it changes; working notes and distant FAQs cannot repair false public
copy. Keep limitations usable, not a wall of warnings.

## Review and deliver within scope

Read the copy without notes: does the reader get the intended product, a concrete
reason to use it, and a relevant action? Check benefit-with-mechanism, actor,
section progression, and factual clauses separately. Preserve good original text
when rewriting adds no value. Never treat exact phrase matching as writing quality.

For an important positioning revision, unless the owner requests self-evaluation,
obtain a cold reading of the draft
without product docs or the author's rationale before a source-informed review.
Use [the meaning review](references/meaning-review.md) for substantive positioning
changes and skill trials. Ask what reason to adopt it is actually stated, not
whether the words sound good. Inspect the opening in isolation as well as the
full page: a correct lower section cannot silently repair the wrong category.
An unexplained reason remains missing even if a knowledgeable reviewer can fill
it in. Keep that diagnostic separate from human research and owner taste. When
an independent reader is unavailable, save the author review and name that limit;
do not relabel it cold, block unrelated useful work, or infer approval.

For test-first requests, save private drafts and follow the requested decision
route: owner acceptance when reserved, or documented author evaluation when
the owner explicitly delegates application. Do not turn the latter into another
approval loop or call it independent validation. Evaluation against a capable
docs-only baseline may produce
ties or losses; retain them. A rewritten authority and a rewritten skill are
different interventions: compare them separately when attributing improvements.
An unresolved owner objection keeps the affected positioning unresolved even
if factual checks pass. Model judgment is not human comprehension or
conversion evidence. Create another skill only for a demonstrated distinct job.

If application is authorized, align the relevant page, metadata, and semantic
siblings without rewriting historical quotations. Run proportionate source/site
checks and keep local, verified, reviewed, and live states separate. A writing
skill neither grants deployment authority nor proves marketing effectiveness.
Keep the selected draft identifiable and compare it with the actual served
opening after applying it. Updating a skill or saving a private draft does not
correct a page that still presents rejected copy. Report the visible headline
and application/publication state, not just that the writing work is complete.

For a substantial reorganization, test the reader's path as well as individual
sentences; use the reading-path check in the meaning review. Shorter is not
better if prerequisites, qualifications or useful destinations disappear.

For a cross-surface pass, record each page's job and whether to revise or retain
it. Read each changed page in full, including captions and secondary sections;
a strong hero cannot repair a contradictory lower paragraph. Keep meaning
consistent without pasting one slogan everywhere. Synchronize visible FAQs and
their structured data, page titles/descriptions, and agent-readable summaries.
Verify cross-page promises against the destination: a working link does not
prove that a named guide exists there or that a command does what its label says.
Preserve executable examples, generated sections, anchors, and commercial terms;
change their owners or generators when necessary, not just rendered copies.