Skip to content
Solidarity Commons Protocol

Writing Standard

The local Pilcrow skill is the house editor for this repository. It lives at .agents/skills/pilcrow.

Use Pilcrow when drafting, auditing, clarifying, tightening, or polishing Markdown and other prose.

Voice

Section titled “Voice”

Use plain, concrete prose. This project already has enough conceptual density from Holochain, cooperative institutions, and legal boundaries.

Do not add a ceremonial documentation voice on top.

Good pages:

  • define terms on first use.
  • spell out solidarity-economy and Holochain-ecosystem acronyms on first use, then use the acronym afterward: community land trust (CLT), employee stock ownership plan (ESOP), distributed hash table (DHT).
  • move examples close to claims.
  • say what is uncertain.
  • name the affected actor.
  • keep regulated boundaries explicit.
  • link to deeper technical material instead of overloading one page.
  • source load-bearing claims with inline reference-style links.

When the acronym itself is a source anchor or glossary term, an inline link is acceptable on first use:

An [employee stock ownership plan (ESOP)](https://www.nceo.org/what-is-employee-ownership/esop-employee-stock-ownership-plan) can buy shares from a departing owner.

Generic technical acronyms such as PDF, API, HTML, URL, DOCX, PPTX, XLSX, SVG, and OCR can remain acronyms.

Pilcrow checks

Section titled “Pilcrow checks”

Use Pilcrow for:

  • clarify when a page is for non-expert readers;
  • tighten when a page drifts into abstractions, weak verbs, or repeated structure;
  • a source-review pass when claims need source checking;
  • polish before publishing or reviewing a larger page.

The strongest local rules for this project are the ones that protect civic and technical clarity.

  • no AI stock openers or chat sign-offs;
  • no abstract claims without concrete examples;
  • no buried lede in decision pages;
  • no parallel-list rhythm that makes every page sound generated;
  • no invented examples for civic or legal workflows.

Source Rules

Section titled “Source Rules”

Prefer reference-style Markdown links for sources. This keeps the prose readable while preserving a checkable source trail:

The International Cooperative Alliance defines cooperatives through democratic member control and shared needs.[ica]


[ica]: https://ica.coop/en/cooperatives/cooperative-identity

Every page should cite real sources for claims about institutions, law, accounting, protocol behavior, external tools, or software capabilities. Use unsourced prose only for project-local choices, clearly marked assumptions, or navigation guidance.

Page shape

Section titled “Page shape”

Most docs pages should use this shape:

  1. State the reader problem.
  2. Give the practical example.
  3. Name the concept or architecture element.
  4. Explain the design consequence.
  5. Link to the source, diagram, or next page.

Decision pages should be stricter:

  1. Context.
  2. Options considered.
  3. Decision.
  4. Consequences.
  5. Follow-up checks.