Connect

Writing it well

How clearly a rule is written matters more than how many rules there are. Write GRAPH.md the way you would brief a new teammate.

The check tells you whether the file has the right shape. Whether assistants write well into your graph depends on the prose. These are the habits that make the difference.

Name a real example, not a quality

"Keep concepts focused and reusable" sounds right, but every assistant reads its own meaning into it. A named example points at one thing:

BAD   Concepts should be focused, reusable and well scoped.

GOOD  GOOD "Optimistic concurrency control": reusable, self standing, one idea.
      BAD "Database stuff": several ideas in a bag. Split it.
      Test: if you cannot finish the sentence "X is ..." in two sentences, it is too big.

Adjectives describe a region; an example describes a point. One good and one bad example from your own graph usually carry more than a paragraph of rules.

Rewrite the examples for your field

Sections tagged [varies by topic] are meant to be rewritten. The template's examples come from software. If your graph is about something else, replace them with examples from it. Two versions of the same section:

## How big is one concept [varies by topic]      # a reading-notes graph
GOOD "Sunk cost fallacy": one idea you will meet again in other books.
GOOD "Spaced repetition": same shape, different field.
BAD "Thinking, Fast and Slow": a book, not an idea. Write it as an Entity.
BAD "Chapter 3 notes": not a concept. That is an Episode.
## How big is one concept [varies by topic]      # a codebase graph
GOOD "Write-ahead log replay": one mechanism, used from several places.
GOOD "Rate limit per key": one rule, one place to change it.
BAD "Backend": a whole area. Use it as a topic, not a concept.
BAD "Fix for issue 482": not a concept. That is a Record or a Decision.

Write down your own rules

Sections tagged [this graph decides] are where your graph differs from others. Write the rules you actually keep repeating to assistants, as concretely as you would say them:

## Read before you write [this graph decides]
Search first (vinc_search) and reuse the ids you get back.
Every pricing decision links to concept:pricing-model with `about`.
Meeting notes go in as documents (vinc_doc_put); only the decisions become nodes.

Sections tagged [schema-fixed] describe how Vinc works. Rewording them is fine, but changing their meaning does not change Vinc. An assistant that follows the changed text will simply write against how Vinc works.

Keep Do not short

A clear example already rules out a lot: once an assistant knows a book is an Entity, it will not make the book a concept. Add a Do-not line only for a mistake you have actually seen, and say why in the same line.

- Do not ratify your own proposal. A person does that.
- Do not create a node for something you did not search for first.
- Do not invent a domain name inline. Propose it and say why.

If the list keeps growing, the examples above it are probably too vague. Fix the examples first.

Stay within 75 lines

The template is already 75 lines, the point where the check starts asking for a fix. When you add a line, take one out: merge two sentences that say the same thing, or drop a template example that does not fit your field. Over 100 lines fails the check.

Test it on an assistant

  1. Save your edit in the app. Assistants read the new text from their next vinc_conventions call.
  2. Start a new session and ask the assistant to restate the rules in its own words. A rule it gets wrong is a rule to rewrite.
  3. Give it a real note to save, then look at what it wrote in the app: the node kind, the title, the topic, the relations.
  4. Run vinc graph-md check to make sure the shape still holds (Check with the CLI).