8000 Plain-language glosses · Issue #41 · kiran-brahma/writing-tool · GitHub
[go: up one dir, main page]

Skip to content

Plain-language glosses #41

Closed
Closed

Description

@kiran-brahma

Parent

#34 — the Obelus v1.2 spec (docs/specs/obelus-v1.2.md). Covers stories 183–184.

Blocked by #35 (the rail moves every panel) and #36 (the glosses link into How this works).

What to build

The app speaks its own glossary with no translation. Pass, Finding, Anchor, Containment, Screening
frame, Connection, Slot, Critic, Judge, Band, Revision, Reader account, Audit account, Violation —
correct in code, on screen with no definition anywhere. Sentences that do not parse for a newcomer:

  • "No Findings dropped outside the target." (ModelPassesPanel.tsx)
  • "Model drift, struck through rather than hidden:" (ModelPassesPanel.tsx)
  • "Structural Passes will run in 4 overlapping chunks — Section by Section…" (ModelPassesPanel.tsx)

Give every panel one plain-language line explaining its own nouns, linking into How this works for
the full definition. Rewrite the sentences above and their siblings so they can be read cold.< 8000 /p>

A gloss is help text, not a concept. No new glossary term, no new component vocabulary.

CONTEXT.md governs code, tests, issues and commits. It does not require UI copy to be
untranslated, and a capitalised Document mid-sentence in help text reads as a contract. UI
sentences use ordinary case; the glossary terms stay the terms.

Where

Every panel under src/editor/, plus src/wire/ConnectionsPanel.tsx,
src/settings/AiSettingsView.tsx, src/workbench/WorkbenchView.tsx and src/library/LibraryView.tsx.
Link targets in src/help/helpContent.ts.

Acceptance criteria

  • Each panel explains its own nouns once, in plain language. (story 183)
  • Each gloss links into How this works, and every link resolves to a section that exists.
    (story 184)
  • The three sentences quoted above are rewritten to be readable without the glossary.
  • UI sentences use ordinary case; glossary terms are unchanged in code, tests and commits.
  • No new term enters CONTEXT.md from this ticket.
  • No gloss praises the Writer's prose or characterises their skill.

Verification

This ticket is copy. Do not write a unit test shaped to look like coverage. A test that every gloss
link resolves to a section id present in helpContent is worth having; the rest is an explicit
observable checklist — panel by panel, the line you added and the sentence you rewrote — which you
state in a comment when you close the ticket.

No DOM layer.

Constitution

Rule 2 applies to the app's own copy as much as to model output: a gloss explains, it never
encourages. Nothing here inserts model-derived text.

Activity

  1. kiran-brahma commented on Sep 24, 2026

    @kiran-brahma
    OwnerAuthor

    Completed in cd3aead.

    Observable checklist: panel-by-panel additions and rewrites

    1. Outline panel (src/editor/OutlinePanel.tsx):
      • Added: "Headings in the document, derived from markdown # marks. Click any heading to jump to it." + "How this works" link to loop.
    2. Metrics panel (src/editor/MetricsPanel.tsx):
      • Added: "Reading time, character counts, and the estimate of what this document would cost to run against your configured critic." + "How this works" link to glossary.
    3. Band panel (src/editor/BandPanel.tsx):
      • Added: "An editorial stance. Each band runs a group of passes focused on one kind of attention." + "How this works" link to loop.
      • Rewrote: "No Findings dropped outside the target." -> "All findings stayed inside the text examined."
      • Rewrote: "${report.droppedAnchors} Anchor${...} dropped outside the target." -> "${report.droppedAnchors} ${... ? "finding fell" : "findings fell"} outside the text examined and ${... ? "was" : "were"} dropped."
      • Rewrote: "Model drift, struck through rather than hidden:" -> "Praise from the model, struck through rather than hidden:"
      • Rewrote: "No Audit account yet. Run the pass to see whether the Document's reasoning holds up." -> "No audit account yet. Run the pass to see whether the document's reasoning holds up."
      • Rewrote: "critic Connection" -> "critic connection"
      • Rewrote: "the Section your cursor is in" -> "the section your cursor is in"
      • Rewrote: "the whole Document" -> "the whole document"
      • Rewrote: "Audit the whole Document" -> "Audit the whole document"
      • Rewrote: "The Starter pack adds them as tickets land." -> "The starter pack adds them as tickets land."
    4. All findings panel (src/editor/FindingsSidebar.tsx):
      • Added: "A copyeditor's mark anchored to an exact quote. Work through them with j / k, dismiss with x, reopen in the rail." + "How this works" link to shortcuts.
    5. Judge panel (src/editor/JudgePanel.tsx):
      • Added: "An independent check that scores each finding and drops false alarms before they reach your queue." + "How this works" link to loop.
      • Rewrote: "Assign a Connection to the judge Slot in Settings before turning the judge on." -> "Assign a connection to the judge slot in settings before turning the judge on."
      • Rewrote: "Default Judge model (cheap and fast): ..." -> "Default judge model (cheap and fast): ..."
      • Rewrote: "Using your custom judge Connection: ..." -> "Using your custom judge connection: ..."
      • Rewrote: "No Findings judged yet. Turn the judge on and run a pass to see findings scored." -> "No findings judged yet. Turn the judge on and run a pass to see findings scored."
    6. Revisions section in Working order rail (src/editor/WorkingOrderRail.tsx):
      • Added: "Snapshots of your document saved on every pass run, milestone, and restore." + "How this works" link to glossary.
      • Rewrote: "Structural Passes will run in 4 overlapping chunks — Section by Section, so headings and transitions stay visible to the Model." -> "Structural passes run in 4 overlapping chunks, section by section, so headings and transitions stay visible to the model."
      • Rewrote: "No Revisions yet. They are created automatically on every pass run, milestone, and restore." -> "No revisions yet. They are created automatically on every pass run, milestone, and restore."
    7. Rule passes panel (src/editor/RulePassesPanel.tsx):
      • Added: "Deterministic checks that run instantly in your browser, without an API key or an external call." + "How this works" link to rules.
    8. Connections panel (src/wire/ConnectionsPanel.tsx):
      • Added: "API configurations for model providers. Your keys never leave this browser." + "How this works" link to rules.
      • Rewrote: "base URL of the Connection you configured" -> "base URL of the connection you configured"
      • Rewrote: "chosen per Slot above" -> "chosen per slot above"
      • Rewrote: "Add Custom Connection" -> "Add custom connection"
    9. Slots panel (src/settings/AiSettingsView.tsx):
      • Added: "Slots connect editorial roles (critic, judge) to a specific provider connection." + "How this works" link to glossary.
      • Rewrote: "Assign a Connection to each Slot..." -> "Assign a connection to each slot..."
    10. Run settings panel (src/settings/AiSettingsView.tsx):
      • Added: "Controls for how passes run: screening frames, token budget limits, and voice profiles." + "How this works" link to loop.
    11. Pass workbench (src/workbench/WorkbenchView.tsx):
      • Added: "The workbench lets you write and edit prompt passes, choose their scope and output shape, and export or restore the starter pack." + "How this works" link to glossary.
      • Rewrote: "critic Connection" / "critic Slot" -> ordinary case
      • Rewrote: "New Pass — not saved yet" -> "New pass — not saved yet"
      • Rewrote: "No model Passes yet. Add one, or restore the Starter pack." -> "No model passes yet. Add one, or restore the starter pack."
      • Rewrote: "Who this Pass is written for. The Reader and the Audit keep their own stance." -> "Who this pass is written for. The reader and the audit keep their own stance."
      • Rewrote: "Ask for help writing this Pass prompt. The assistant sees only your request and the prompt above — never your Document." -> "Ask for help writing this pass prompt. The assistant sees only your request and the prompt above, never your document."
      • Rewrote: "What should this Pass look for?" -> "What should this pass look for?"
      • Rewrote: "Whole Document" -> "Whole document"
    12. Library view (src/library/LibraryView.tsx):
      • Added: "The library holds all documents saved in this browser. Everything stays local until you export or back up." + "How this works" link to glossary.
      • Rewrote: "{count} Document(s) in this browser" -> "{count} document(s) in this browser."
      • Rewrote: "New Document" -> "New document"
      • Rewrote: "Search Documents" -> "Search documents"
      • Rewrote: "No Documents yet. Create one, or start typing in the Scratchpad." -> "No documents yet. Create one, or start typing in the scratchpad."
      • Rewrote: "No Documents match this search." -> "No documents match this search."
      • Rewrote: "open Finding(s)" -> "open finding(s)"
    13. Backup panel (src/library/BackupPanel.tsx):
      • Added: "A backup saves your whole library to one file; a bundle exports a single document with its revisions and findings." + "How this works" link to glossary.
      • Rewrote: "Back up the Library before clearing this browser." -> "Back up the library before clearing this browser."
      • Rewrote: "Back up Library" -> "Back up library"
      • Rewrote: "Import Document bundle" -> "Import document bundle"
      • Rewrote: "A restore replaces the Library." -> "A restore replaces the library."
      • Rewrote: "every Document, Revision, Finding and setting... The current Library..." -> "every document, revision, finding and setting... The current library..."
      • Rewrote: "Replace Library" -> "Replace library"
    14. Model praise in row and accounts:
      • src/editor/FindingRow.tsx: "Model drift:" -> "Praise from the model:"
      • src/editor/AccountDisplay.tsx: "Model drift, struck through rather than hidden:" -> "Praise from the model, struck through rather than hidden:" and "Model drift:" -> "Praise from the model:"
    15. App shell (src/App.tsx):
      • Updated helpReturn to support "editor" | "library" | "settings" | "workbench".
      • Rewrote: "Could not save your Document: ..." -> "Could not save your document: ..."
      • Rewrote: "Could not import that Markdown: ..." -> "Could not import that markdown: ..."

    Automated verification

    • Unit tests added in src/help/helpContent.test.ts verifying all 13 panel keys have defined glosses, each gloss link resolves to a valid section id in helpContent.ts, ordinary sentence case is followed, em dashes are absent, and no praise or skill characterization exists.
    • 890 unit tests passing cleanly.
    • agent-gates check clean.
    • Constitution harness 18/18 passing cleanly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentSpec is ready for an agent to implement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      0