FabledScribe/plugin/skills/using-scribe/SKILL.md

---
name: using-scribe
description: Use at the START of every session, and before answering anything about the operator's work or starting any task — establishes the Scribe-first reflex. FIRST ACTION of a session: call list_always_on_rules() (and enter_project when a repo/project is in scope) to load the operator's binding rules. Then recall before acting, update over duplicate, plan in Scribe not in files.
---

# Using Scribe

Scribe is the operator's self-hosted system of record (notes, tasks, issues,
projects, milestones, systems) and rulebook, reachable
through the bundled `scribe` MCP server. Its value is mostly in what it
**already holds** — so make reading it a reflex, not something you wait to be
asked for.

## Do this first (every session)

**Pull the standing rules yourself — do not wait for them to be handed to you.**
At the start of a session, before substantive work, call
`list_always_on_rules()` to load the operator's always-on rules. If the working
repo maps to a Scribe project (you're in a known repo, or `list_repo_bindings`
shows a binding), call `enter_project(id)` instead/as-well — it returns the
project plus its applicable rules, open tasks, and recent notes in one shot.

Do this actively. A SessionStart hook *may* also inject a rule index, but treat
that as a bonus, not a precondition: it can be absent (e.g. when the instance is
unreachable, or the token didn't reach the hook), so the reliable path is this
explicit pull. Rules loaded this way are **binding** for the session.

## Scribe holds these functions — don't keep a second copy

This plugin makes Scribe the home for the operator's **rules, recall, and
planning** — the jobs Claude's native auto-memory would otherwise do. When the
plugin is present, route those jobs to Scribe and **do not also write them to
native memory**: codify rules with `create_rule` / `create_project_rule`,
capture durable knowledge as Scribe notes, and keep plans in Scribe milestones
(via `start_planning`) — not in `MEMORY.md` or `CLAUDE.md`. One copy, in Scribe; let any existing local
memory shrink as Scribe takes over. Don't maintain both stores in parallel.

Two constraints on *how* that's achieved:

- **Steer behavior; never flip a native switch.** The plugin must work with
  native auto-memory at its default (ON). Never tell the operator to set
  `autoMemoryEnabled:false` or otherwise disable a built-in function to make
  Scribe "win" — a setting the operator may not know was changed (and wouldn't
  know to restore) is exactly the hidden breakage to avoid. You replace memory's
  functions by *doing the work in Scribe*, not by turning memory off.
- **A Scribe-shaped hole is acceptable.** If the plugin is later removed, the
  operator recovers context over time — that's fine. You do **not** need to keep
  native memory as a self-sufficient fallback. The only thing to avoid is
  breakage caused by a settings change the operator didn't make knowingly.

## The reflex

1. **Recall before acting.** Before answering a question about the operator's
   work, or starting a task, `search` Scribe (and `list_tasks` / `list_notes`)
   for related prior work — an existing task, decision, or note — instead of
   re-deriving it or opening a duplicate. When a project is in scope, pass its
   `project_id` so results stay scoped.

2. **Standing rules are binding.** Load them via `list_always_on_rules()` at
   session start (see "Do this first"); treat every one as binding. Pull a
   rule's full statement with `get_rule(id)` when it's about to bite. When a
   project is in scope, `enter_project(id)` also returns its applicable rules.

3. **Update over duplicate.** When recording, prefer updating an existing
   note/rule/task over creating a new one. Search first; revise what's there.

4. **When you plan, plan in Scribe.** Work with an *arc* — several steps toward
   one goal — gets a plan, and a plan is a milestone: `start_planning(project_id,
   title)` creates one whose `body` holds the design, each step is its own task
   under it (`create_task(milestone_id=...)`), progress goes in work-logs
   (`add_task_log`). Work without an arc (a fix, a one-file change, a question)
   is just a task — don't wrap it in a milestone. Either way, do not write
   plans/specs to local `.md` files. See the **writing-plans** skill.

5. **Keep state honest.** Set a task `in_progress` when you start it, `done` the
   moment it's complete; log progress as you go.

6. **Fixes are issues, not work-logs.** When you fix a problem — even one solved
   in passing — record it as its own issue (`create_task(kind="issue")`) with
   symptom → root cause → fix, optionally linked to the task it arose from
   (`arose_from_id`) and the subsystem it touches (`system_ids`). Don't bury a
   fix as a work-log line on whatever task happened to be open.

## Stay inside the active project's scope

Once a project is in scope — you called `enter_project`, or the working repo is
bound — confine the session to it:

- **Pass that `project_id` to every read** (`search`, `list_tasks`,
  `list_notes`). An unscoped read bleeds every other project's work into your
  context.
- **Only reference or offer work on the in-scope project.** Don't surface,
  suggest, or start work on other projects unless the operator explicitly widens
  scope.
- If something clearly belongs to a *different* project, say so and **ask before
  switching** — never silently operate cross-project.

## Where a new rule goes

When codifying a rule, pick its home by **who it should bind** — and keep
shared homes general:

- **Always-on rulebook** (`create_rule` in an `always_on` rulebook) — universal
  norms that bind *every* project. Cross-project standards only.
- **Subscribed rulebook** (`create_rule` + `subscribe_project_to_rulebook`) — a
  reusable, *themed* module of general rules that binds only projects that opt
  in (e.g. a review checklist → every service). Themed, but project-agnostic.
- **Project rule** (`create_project_rule`) — anything specific to one project
  (its files, paths, quirks).

Both rulebook tiers are shared, so their rules stay general; they differ in
**reach** (all vs opt-in), not generality. Names one project's specifics →
project rule; a standard a category shares → subscribed rulebook; a universal
norm → always-on rulebook. Never put project-specific detail in a shared
rulebook — it leaks to every other project that gets it.

**First ask whether it's a rule at all.** A rule is prose you have to remember
and apply; Scribe's other entities are structure a tool can resolve and check.
Visual standards belong in a **design system**, not a rulebook — a token can be
inherited, resolved per mode, rendered to a stylesheet and diffed against code,
and none of that survives being written as a rule. A repeatable procedure is a
**process**; reusable code is a **snippet**. Reach for a rule when the thing
really is a standing instruction about how to work.

## Building UI: the project's design system binds

`enter_project` returns a `design_system` when the project has one, with the
guidance **chain-merged** — the house style it inherits plus its own departures
from it. Treat it the way you treat a rule.

Before writing a colour, size, radius, weight or duration by hand, reach for a
token: `resolve_design_system(id)` for the values, or
`get_design_system_stylesheet(id)` for the rendered sheet. A literal is a value
stated outside the system, so it can never follow a palette change — and
nothing will tell you it drifted.

## Other Scribe process-skills

This plugin also ships focused process-skills — writing-plans, systematic
debugging, verification, and brainstorming. Reach for the matching one when its
situation arises, the same way you reach for this skill.