8000 writing-tool/CONTEXT.md at v1.3-47 · kiran-brahma/writing-tool · GitHub
[go: up one dir, main page]

Skip to content

Latest commit

 

History

History
278 lines (214 loc) · 9.55 KB

CONTEXT.md

File metadata and controls

278 lines (214 loc) · 9.55 KB

Obelus

A browser-only writing tool that uses language models as a copyeditor and a judge, never as a ghostwriter. This glossary is the project's shared language: code, tests, issues and commits use these terms and no others.

The work

Writer: The person using Obelus, and the author of everything in it. Avoid: user, author, owner, operator

Document: One piece of writing. The only noun for a piece of work. Avoid: draft, piece, article, text, file

Section: A heading-delimited division of a Document. Avoid: chapter, part

Outline: The list of a Document's Sections, derived from its headings; the Writer jumps between Sections by it, and a structural pass receives it. Avoid: table of contents, headings list

Paragraph: A block of prose within a Section, and the unit a local pass is examined against. Avoid: block

Revision: One saved point in a Document's history. An auto-revision is taken on a debounce; a flagged revision is marked by the Writer as a milestone and carries a note. Avoid: snapshot, version, save, checkpoint

Library: Every Document held in this browser. Avoid: workspace, project, vault

Backup: One file holding the whole Library, so an eviction is survivable. A backup excludes API keys unless the Writer explicitly opts in. Avoid: archive, dump, snapshot, export

Restore: Replacing this browser's Library with a Backup, behind an explicit confirmation. The mechanism is an import; the action is a restore. Avoid: load, sync, recover

Bundle: One Document as a single file, carrying its Revisions, Findings, Run results and Reader accounts, so it can move intact. Avoid: package, archive, export

Analysis

Pass: A configured analysis of a Document — a rule pass or a model pass — with a scope and an output shape. Avoid: check, task, lint

Rule pass: A Pass implemented as deterministic rules over text, so it can neither praise nor rewrite. Avoid: Tier 1, mechanical pass, lint

Exclusive rule pass: A Rule pass that runs alone: while it is on, the other rule passes are held, so its report is not buried among theirs. George Orwell's rules is one. Avoid: solo mode, profile, override

Model pass: A Pass implemented as a call to a model. Avoid: Tier 2, AI pass, LLM pass

Rule config: The editable data behind a rule pass: its word lists, patterns and windows. Avoid: settings, options, config

Voice list: The words and phrases the Writer has declared as theirs, which no Pass may flag as a problem. Avoid: allowlist, exemption list, ignore list, protected words

Pass scope: How much of a Document a Pass is shown: document, section or paragraph. A structural pass is document-scope; a local pass is paragraph-scope. Avoid: range, coverage

Working order: The recommended sequence in which the Writer works the Passes — structure, then paragraph, then word — derived from Pass scope. A recommendation, never a gate. Avoid: revision order, pass order, pass stage

Band: One of the three divisions of the Working order — structure, paragraph, word — derived from a Pass's kind and scope rather than stored. The Writer navigates by Band; every Band is one click away from every other, and no Band is gated on another. Avoid: stage, tier, phase, step, section

Rail: The surface the Writer navigates by Band: the reference strip, the Band control, the selected Band's Passes with their Findings and account 59A3 s, the Judge, and milestones and Revisions. It collapses so the prose has the width. Avoid: sidebar, panel, drawer, nav

Target: The text a Run is asked about. Avoid: selection, focus, scope

Containment: The rule that a Finding anchored outside the Target is discarded, with the count reported. Avoid: scope enforcement, filtering, pruning

Run: One execution of a Pass against a Revision, producing Findings. Avoid: pass run, critique, job, analysis

Finding: One problem a Run reports about the prose, anchored to the text it concerns. Avoid: comment, note, issue, suggestion, flag, error

Current Finding: The one open Finding the queue's selection is on. Its Highlight is distinguished from the others and the Editor scrolls to it, so the prose and the queue never disagree about where the Writer is. Avoid: active finding, selected finding, focused finding

Anchor: The data tying a Finding to its text: the quoted span, with an offset as a hint. Avoid: position, range, mark

Highlight: The visual rendering of an Anchor. The Current Finding's Highlight is distinguished from the rest. Avoid: underline, marker

Callout: The popover a click on a Highlight opens beside the prose: the open Findings on that text, with the queue's verdicts. It does not change the Current Finding, so the Rail stays where the Writer left it (ADR 0011). Avoid: tooltip, popup, card

Orphaned: The condition of a Finding whose quoted text can no longer be found, so it points nowhere. A condition, never a status. Avoid: lost, stale, dangling

Violation: Praise or rewrite-shaped content caught in model output. About the model misbehaving, never about the prose. Avoid: breach, infraction, error

Praise: Encouragement in model output. Rule 2 forbids it, and the praise linter is the check for it. Avoid: encouragement, positive feedback

Quarantined rewrite: Model-written prose that is displayed but can never enter a Document. Avoid: diagnostic rewrite, proposed text, suggestion, draft

Starter pack: The default Pass set that ships with Obelus. Avoid: presets, defaults, built-ins

Roles and connections

Provider: A vendor that serves models: OpenAI, Anthropic, Google, OpenRouter, Ollama. Avoid: vendor, service, backend

Protocol: A wire format: openai-shaped, anthropic-shaped or gemini-native. Avoid: API, dialect, provider API

Connection: A configured route the Writer creates: a Protocol, a base URL, a key and a concurrency cap. The model a Run uses is chosen per Slot, not on the Connection; a Connection's own model is only a fallback for a Slot that names none. Avoid: provider config, provider, endpoint, credentials

Slot: A named place a Connection and a model are assigned. There are two: critic and judge. The two Slots may share one Connection while naming different models, so the Judge can be independent without a second route to the Provider. An empty model inherits the Connection's own. Avoid: role, position, model slot

Critic: The Slot that runs model passes and finds problems. Avoid: reviewer, editor, coach

Judge: The Slot that compares two versions of a passage and answers which is clearer, receiving the two passages and nothing else. Avoid: evaluator, scorer, arbiter

Screening frame: The Critic's standing instruction to read the piece as an editor screening a submission. It applies to the Critic only. Avoid: persona, system prompt

Skimmer: A screening frame: a reader with no time and no patience. Avoid: busy reader, skimming

Skeptic: A screening frame: a hostile domain expert who doubts the claim. Avoid: adversary, critic

Practitioner: A screening frame: someone who has to act on this advice this week. Avoid: operator, user

reader: The human who reads the finished prose. Always the human. Avoid: audience, consumer

Reader pass: The model pass that reconstructs what a reader takes away from a Section. Avoid: Reader, reconstruction, takeaway

Reader account: A Reader pass's output: what a Section says, what a distracted reader would miss, and the gap between the two. Avoid: summary, reader report

Audit pass: The model pass that examines whether a piece's reasoning holds up. Avoid: review, critique, argument pass

Audit account: An Audit pass's output: the piece's argument map, any fallacies or definition gaps, and the findings that matter most. Avoid: report, notes, argument account

Lard Factor: The share of an earlier Revision's words that a later Revision removes, so progress is visible rather than felt; it is negative when the later Revision is longer. A signal, not a verdict: it gates nothing. Avoid: lard score, cut ratio, reduction

The judge's answers

Verdict: The Judge's answer: which passage is clearer, how confident it is, and its reasons with quoted evidence. Avoid: score, rating, result, judgment

Unstable: The condition of a Verdict that changes when the passage labels are swapped. Reported as unstable rather than as a preference. Avoid: flaky, inconsistent, tie

Prediction: The Writer's own call, recorded before a Judge run, of which passage is clearer. Held in memory for the session only, never persisted, never sent to a model, and never a gate on the run; shown beside the Verdict so the Writer can see whether their judgment agrees with the Judge's. Avoid: guess, bet, expectation

Status

Finding status: One of exactly three: open, addressed, declined. A declined Finding records why — the advice was rejected, or the model breached the constitution. Avoid: resolved, rejected, dismissed, closed, done

Document status: One of exactly three: draft, revising, done. Avoid: state, stage, progress

The constitution

Constitution: Obelus's standing constraints: model output is analysis and never prose, and every request leaves the Writer's browser. Avoid: invariants, principles, rules, guidelines

Rule 1: The source method's first rule — the Writer may not use a single word a model suggests. Avoid: the rules, the suggestion ban

Rule 2: The source method's second rule — avoid encouragement. Avoid: the rules, the praise ban

0