scribe

Files (23)

• plugin.json · .claude-plugin/
• .python-version
• .standalone-db
• SKILL.md
• persona-cards.tsx · dashboard/components/
• pieces-board.tsx · dashboard/components/
• score-trajectory.tsx · dashboard/components/
• voice-profile-panel.tsx · dashboard/components/
• lib.ts · dashboard/
• page.tsx · dashboard/pages/scribe/
• page.tsx · dashboard/pages/scribe/piece/[id]/
• route.ts · dashboard/routes/personas/
• route.ts · dashboard/routes/piece/[id]/
• route.ts · dashboard/routes/pieces/
• route.ts · dashboard/routes/profile/
• hub.yaml · dashboard/views/
• piece.yaml · dashboard/views/
• hooks.json · hooks/
• pyproject.toml
• quality-checks.yaml
• schema.tql
• scribe.py
• skill.yaml

SKILL.md (first lines)

# Scribe — The Communication Expert

Writing in *your* voice for *your* audience is the widest gap between basic and
advanced AI use. Scribe closes it with three assets: a **voice profile** built
from your best writing plus aspirational samples, **audience personas** that
review every draft, and **dimension-scored feedback** instead of "I don't like
it". The bar is "sounds exactly like you"; the failure mode is
generic-pleasant-forgettable.

**Key principle:** the script stores and queries; Claude does the sensemaking —
the linguist analysis, the drafting in voice, the persona role-play, and the
scoring. Follow [operating-principles.md](../../docs/operating-principles.md):
primer notes, interview-first, plan/execute split, and explicit
⏸ OPERATOR CHECKPOINT moments.

---

## 1. Quick Start

```bash
# All commands: uv run python skills/scribe/scribe.py <command> --flags
CLI="uv run python skills/scribe/scribe.py"

# Store your best writing
$CLI add-sample --name "Q3 board update" --kind own --doc-type board-update \
    --content-file q3-update.md --why-it-works "Landed a hard message without spin"

# Create the voice profile
$CLI create-profile --name "Default Voice"

# Define a reader persona
$CLI add-persona --name "Skeptical board member" \
    --cares-about "runway, focus, evidence over narrative" \
    --skeptical-of "hockey-stick projections, adjectives without numbers" \
    --action-drivers "a clear ask with a deadline" \
    --reading-context "board packet, 20 pieces to read, 90 seconds each"

# Open a piece — ALWAYS capture the primer
$CLI create-piece --name "Series B announcement email" --type team-email \
    --goal "Team feels momentum, nobody worries about dilution" \
    --primer "ok so the thing I keep coming back to is..." \
    --targets persona-abc123 persona-def456

# Draft → review → score → iterate
$CLI add-draft --piece piece-xyz --content-file draft1.md
$CLI add-review --draft draft-1a2b --persona persona-abc123 --would-act no \
    --content "Clear until para 3. I'd stop at the dilution hand-wave. Missing: the number."
$CLI add-scores --draft draft-1a2b --clarity 7 --concision 5 --voice 8 --persuasion 6 --overall 6 \
    --content "Structure is right. Paras 3-4 hedge; cut 40% and state the dilution number plainly."
```

**Command output pattern:** every command emits a single JSON object to stdout;
`report-piece` emits Markdown. `uv run` emits a `VIRTUAL_ENV` warning to stderr —
always use `2>/dev/null` when piping output to a JSON parser, never `2>&1`.

---

## 2. Voice Profiling Workflow

The goal: a living style guide that captures how the operator actually writes —
and how they *want* to write.

**⏸ OPERATOR CHECKPOINT — collect the corpus.** Ask the operator for their best
writing across doc types: board updates, team emails, LinkedIn posts, talks,
essays. "Best" means *they* are proud of it, not that it performed well. Store
each with `add-sample --kind own --doc-type ... --why-it-works ...`. Ask why
each one works — that answer is data.

**Agent-as-linguist analysis.** Read every `own` sample and write an analysis
that names the patterns the operator cannot articulate about themselves:

- **Rhythm** — sentence length variance, where they punch short, where they run long
- **Sentence structure** — fronting habits, clause stacking, fragment tolerance
- **Rhetorical preferences** — how they open, how they land an ask, humor register,
  concrete-vs-abstract ratio, favorite pivots ("but here's the thing")
- **Tells** — words and constructions that make text unmistakably theirs

Store it: `add-analysis --about <profile-or-sample-id> --content-file analysis.md`.

**Aspirational samples.** Ask which writers the operator admires and store
excerpts with `--kind aspirational`. This is not copying — it's augmentation
toward how they *want* to sound. Analyze what the admired writing does that the
operator's doesn't yet.

**Merge into the living style guide.** Synthesize own-analysis + aspirational
gaps into a style guide (concrete rules with examples, not adjectives) and save
it with `create-profile --guide-file` or `update-profile --guide-file`.

**⏸ OPERATOR CHECKPOINT — approve the guide.** Walk the operator through it.
When they say "yes, that's me / that's who I want to be", set
`update-profile --status active`. The guide is *living*: after pieces ship,
fold in what the operator edited by hand (`--status evolving` while reworking).

---

## 3. Audience Personas

Every piece is written *for someone*. Build detailed reader personas — not
demographics, but decision psychology:

- `--cares-about` — what this reader actually cares about
- `--skeptical-of` — what triggers their doubt
- `--action-drivers` — what makes them act rather than nod
- `--reading-context` — where/when/how they read (phone at 11pm; board packet
  among 20 others; LinkedIn feed at half-attention)

Interview the operator to build these — they know their readers; the personas
make that knowledge executable. Reuse personas across pieces via
`--targets` / `--add-target`.

---

## 4. Piece Workflow

Statuses: `planning → drafting → persona-review → operator-review → final → shipped`.

1. **Create (⏸ OPERATOR CHECKPOINT — primer).** `create-piece --primer "..."`.
   The primer is the operator's messy brain dump — voice-dictated is ideal.
   Never require structure; never skip it. Link `--targets` personas.

From sciknow-io/alhazen-skill-personal-assistant, MIT.

More from sciknow-io/alhazen-skill-personal-assistant