8000 How this works, and first run · Issue #36 · kiran-brahma/writing-tool · GitHub
[go: up one dir, main page]

Skip to content

How this works, and first run #36

Closed

Description

@kiran-brahma

Parent

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

What to build

Rule 1 and Rule 2 are the reason Obelus exists. They are in README.md, in DESIGN.md and in the
prompts, and nowhere a Writer using the app will see them. There is no first run, no empty state that
says what to do, and no page that explains the method.

Build How this works: a static destination on the PrivacyView pattern carrying Rule 1 and Rule
2 in full, the three-step loop (a model finds flaws → the Writer rewrites → a context-free Judge
compares), a glossary of the terms the UI uses, and the shortcuts. It is a destination, not a note,
so the two Rules have a permanent home in the product rather than living in something the Writer
dismisses once.

Then a first-run note in the Editor body — not a modal — that says the rule passes have already
run, says where to look, links to How this works, and is dismissible. Dismissal is remembered in the
existing settings key-value store, so no Dexie migration is needed.

Finally, an empty Scratchpad says what to do rather than showing an empty box.

Consequence to state, not to solve: settings travel in a Backup, so a Restore carries "dismissed" and
a Writer restoring onto a fresh browser does not meet the note again. That is correct — they are not
new.

Where

  • src/help/HowThisWorksView.tsx and src/help/helpContent.ts — new, mirroring
    src/privacy/PrivacyView.tsx and src/privacy/privacyContent.ts including the content test.
  • src/App.tsx — the destination and the first-run note.
  • src/storage/settings.ts, src/useDocument.ts — the dismissal key.

Acceptance criteria

  • A How this works page states Rule 1 and Rule 2 in full, explains the loop, defines the tool's
    terms and lists the shortcuts. (story 167)
  • A dismissible first-run note in the Editor body points at it and says the rule passes have
    already run. It is not a modal. (story 168)
  • Dismissal is remembered across reloads via the settings store; no Dexie migration is added.
    (story 169)
  • An empty Scratchpad says what to do. (story 170)
  • The page is a destination reachable at any time, so the two Rules survive dismissal of the note.

Verification

A content test on helpContent mirroring src/privacy/privacyContent.test.ts — assert Rule 1 and
Rule 2 are present by their substance, and that the shortcut list matches the keys the app actually
binds. A pure test on the dismissal setting's default and round-trip.

No DOM layer. State the observable checks you ran for the note and the empty state.

Constitution

The page describes the constitution; it does not weaken it. Nothing here inserts model-derived text.
No copy in the note or the page may praise the Writer's prose — it has not read any.

Note for the ticket that follows: this makes a fourth destination beside the Pass workbench, AI
Settings and Privacy, which #44 has to arrange.

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