@oneie/claude 0.4.0 → 0.6.0

package/skills/typedb/reference/research-notes-2026-04.md

@@ -0,0 +1,169 @@
+# TypeDB Paper Corpus — Research Notes
+
+Collected 2026-04-20. Source: TypeDB blog, fundamentals docs, and the TypeDB 3.0 GitHub roadmap (ACM paper itself is paywalled).
+
+## 1. TypeQL (PACMMOD 2024) — Dorn & Pribadi
+
+**Venue:** ACM SIGMOD/PODS 2024, Proceedings of the ACM on Management of Data 2.2 (PODS), Article 110, May 2024.
+**Award:** Best Newcomer Award, SIGMOD/PODS 2024.
+**DOI:** 10.1145/3651611.
+**Canonical URL:** https://typedb.com/papers/typeql-theory
+
+### Core thesis
+
+The paper introduces the **Polymorphic Entity-Relation-Attribute (PERA) data model**, grounded in modern type theory, accessible through classical conceptual modeling, queried via TypeQL.
+
+### Key technical contributions
+
+1. **"Queries as Types"** — a generalization of Wadler's "Propositions as Types". In TypeQL, *the user constructs types in order to formulate queries*. This is the philosophical pivot away from SQL's operational model (sequences of table transformations).
+2. **Relations as dependent types** — characterized as "dependent types that hold unique object identifiers".
+3. **Attributes as independent or dependent types** — dependent attributes hold literal values.
+4. **Type functions** — an emergent feature where dependent types and subtypes mix, "neatly generalizes Datalog-like reasoning".
+5. **Subtyping + polymorphism** — TypeQL uses "interfaces" where other languages say "typeclasses" (Haskell) or "traits" (Rust).
+
+### Contrast with other query languages
+
+- **SQL** — operates on tables, algebraic/operational viewpoint. Queries are sequences that transform tables into tables.
+- **NoSQL/Document** — aggregation pipelines over documents, no type system.
+- **Cypher / SPARQL** — pattern-based and declarative, but "lack a sophisticated type system".
+
+## 2. TypeDB 3.0 — GitHub Roadmap (Issue #6764)
+
+**Source:** https://github.com/typedb/typedb/issues/6764
+
+### API breaking changes
+
+- **Sessions removed** — replaced by three transaction types (read / write / schema).
+- **Thing / Type hidden** — removed from public-facing interfaces.
+- **Concept API dropped** — replaced by enhanced TypeQL. All operations go through queries now.
+
+### TypeQL language additions
+
+- **Functions** — replace `rule` syntax from 2.x (now the only way to express derivation logic).
+- **Pipelines** — chainable streaming operations across all clauses (the big one).
+- **Cascading delete** — delete one thing, cascades to dependent attributes.
+- **Default dependent attributes**.
+- **Struct value types** — compound values.
+- **List attribute ownerships** — `owns name[]`.
+- **Compound keys** — roles can act as keys.
+- **Abstract attribute hierarchies** — abstract attributes without forcing a value type.
+- **Attributes forbidden from playing roles or owning attributes** — enforces a cleaner model.
+- **Enumerated value restrictions** — `value X @values("a", "b")`.
+- **Regex as annotations**.
+
+### Relation implementation
+
+- Indexed relations (query optimizer).
+- Virtualized role instances (memory overhead reduction).
+
+### Rejected proposals
+
+- Immutable relations.
+- Prohibition on playing identical roles multiple times in one relation.
+
+## 3. Fundamentals — Polymorphic Schema Example
+
+Canonical example from https://typedb.com/fundamentals/typedb-polymorphic-database
+This is the "filesystem / user-group / resource" schema TypeDB uses to teach polymorphism.
+
+```typeql
+define
+
+entity user,
+    owns email,
+    owns password-hash,
+    owns created-timestamp,
+    owns active,
+    plays resource-ownership:resource-owner;
+
+entity admin sub user,
+    plays group-ownership:group-owner;
+
+entity user-group,
+    owns name,
+    owns created-timestamp,
+    plays group-ownership:group,
+    plays resource-ownership:resource-owner;
+
+entity resource @abstract,
+    owns id,
+    owns created-timestamp,
+    owns modified-timestamp,
+    plays resource-ownership:resource;
+
+entity file sub resource,
+    owns path;
+
+entity directory sub resource,
+    owns path;
+
+relation ownership @abstract,
+    relates owned,
+    relates owner;
+
+relation group-ownership sub ownership,
+    relates group as owned,
+    relates group-owner as owner;
+
+relation resource-ownership sub ownership,
+    relates resource as owned,
+    relates resource-owner as owner;
+
+attribute id @abstract, value string;
+attribute email sub id;
+attribute name sub id;
+attribute path sub id;
+attribute password-hash, value string;
+attribute event-timestamp @abstract, value datetime;
+attribute created-timestamp sub event-timestamp;
+attribute modified-timestamp sub event-timestamp;
+attribute active, value boolean;
+```
+
+**What it teaches:**
+- Abstract entities (`@abstract`) with `sub` inheritance.
+- Relation inheritance with **role aliasing**: `relates group as owned` (subtype role renames a supertype role but keeps hierarchy).
+- Abstract attribute hierarchies: `attribute id @abstract, value string;` with `attribute email sub id;`.
+- Interface polymorphism via `plays X:Y`.
+
+### Polymorphic query example
+
+```typeql
+match
+  $resource isa resource;
+fetch {
+  "resource": {
+    "id": $resource.id,
+    "event-timestamp": [ $resource.event-timestamp ],
+  }
+};
+```
+
+Returns every resource + every subtype (file, directory). The square brackets on `event-timestamp` indicate this is a **list** — because `created-timestamp` and `modified-timestamp` are both subtypes of `event-timestamp` and a resource owns one of each, the polymorphic fetch returns both.
+
+## 4. "Inside TypeDB: The Next Chapter" — Dec 2025
+
+Highlights from the latest company all-hands (Callum = interim CEO, Joshua = CTO):
+
+- **TypeDB 3.0 delivered early 2025** — "we delivered TypeDB 3 which is what we believe to be the most commercially viable version".
+- **Rust rewrite** — "after we spent some time rebuilding it in Rust and extending the language further". Highly-available cluster is the next rewrite target.
+- **Positioning** — "fourth category of database" alongside relational, graph, document.
+- **Benchmarks** — "competitive and surpassing Neo4j" on their first Rust optimization pass.
+- **TypeDB Studio** — now web-based (was Kotlin desktop), connects to any local or TypeDB Cloud server over HTTP.
+- **Vibe Querying** — agentic TypeQL-generation on GPT-5, embedded in docs, studio, chatbot.
+- **Knowledge graphs** — repositioned as the primary commercial use case alongside "intelligent systems" and "agentic apps".
+- **Commercial pivot** — after 10 years as a research org, 2025 was the year they "shifted from research-focused organization to a commercial company".
+
+## 5. Video corpus index
+
+See `/tmp/typedb-research/videos/index.tsv`. 15 talks, 2021–2026, 640K plain text.
+
+Most relevant for a refined skill:
+- `e0lmTSb-rzY` — Introduction to TypeDB and TypeQL (the canonical onboarding, 5,360 views).
+- `LMzZoq6fUqg` — Intro to TypeDB - A New Programming Paradigm (2024 presentation).
+- `IJomvpKbevk` — Lecture: The Polymorphic Data Model With Types (87 mins, 2024, SIGMOD-paper deep-dive).
+- `MF2vaEo3o58` — Lecture: Type Theory as the Unifying Foundation (Nov 2023).
+- `2S0zPXQCy0U` — Lecture: Why We Need a Polymorphic Database (Dec 2023).
+- `LS6C4Gl9ldU` — Inside TypeDB: The Next Chapter (Dec 2025, latest).
+- `ffGXheePzKQ` / `-qtqIpl2ntw` / `2YUUPm_O3mU` — Origins podcast series (Rust rewrite context).
+- `XZWV3NlnMJA` — Inference in TypeDB (2021, but still relevant to how functions generalize the old rules).

package/skills/workflow/SKILL.md

@@ -0,0 +1,51 @@
+# Workflow — Author + Run SOPs from Claude Code
+
+**A workflow is a DAG of typed steps; every step compiles to `signal(receiver, data)`. Edit it as a validated diff, run it, watch the path learn.**
+
+Copy-structure source: `packages/claude/skills/signal/SKILL.md`.
+
+## The eight step kinds (LOCKED)
+
+`trigger · tool · skill · agent · condition · human · delay · sell` — read top-to-bottom: what starts it · what does the work (tool→skill→agent autonomy ladder) · what shapes the flow. `human`/`delay`/`sell` suspend the run; `condition` routes; `sell` resumes on `checkout:resume`. Full contract: `one-ie/CLAUDE.md § Workflow step kinds` + `text/workflows-plan.md`.
+
+## The tools (MCP + CLI, same receivers)
+
+| Goal | MCP tool | CLI |
+|---|---|---|
+| what do I have? | `workflow_list` | `oneie workflow list --slug S` |
+| inspect a graph | `workflow_get` | `oneie workflow pull <id> --slug S` |
+| change it | `workflow_apply_diff` (simulate-first) | `oneie workflow push <id> <diff.json> --slug S [--commit]` |
+| run it | `workflow_run` | `oneie workflow run <id> --slug S` |
+| monitor runs | `workflow_runs` | — |
+
+## The diff grammar (WorkflowDiff)
+
+`@oneie/sdk` `WorkflowDiffSchema` — `add[]` (tempId·kind·name·config·position?) · `remove[]` (step ids) · `connect[]` (source·target·condition?) · `disconnect[]` · `update[]` (stepId·field·value).
+
+- **Simulate first.** `workflow_apply_diff` validates the WHOLE diff — DAG acyclicity included — without persisting and returns the projected step count. Pass `commit:true` (MCP) / `--commit` (CLI) to persist.
+- **`update.field`** accepts `name` · `config` · `position` only. `exit-condition` and `owner` are TypeDB-owned and return **`unsupported_field`** — the grammar refuses them loudly rather than silently dropping.
+- **tempId → real id.** New steps carry a client-side `tempId`; `connect`/`update`/`$step.<tempId>.field` refs are rewritten to the persisted id on commit.
+
+## Recipe — "add a human approval before the sell step"
+
+1. `workflow_get` → find the sell step's id and its incoming edge.
+2. `workflow_apply_diff` (simulate): `add` a `human` step (config `{"mode":"approve"}`), `disconnect` the old edge into sell, `connect` prev→human and human→sell.
+3. Review the projected step count, then re-send with `commit:true`.
+
+## Connect Claude Code
+
+`claude mcp add oneie -e ONEIE_API_KEY=<your-api-key> -e ONEIE_API_URL=https://api.one.ie -- npx -y @oneie/mcp` — mint a key at `/profile/api-keys` (never paste key bytes into a shared file).
+
+## Works With
+
+| Skill | Because |
+|---|---|
+| `/signal` | every step compiles to one signal |
+| `/mcp` | the five `workflow_*` tools |
+| `/cli` | the `oneie workflow` group |
+
+## See Also
+
+- `text/workflows-plan.md` — the machine's spec
+- `text/dictionary.md` — canonical names
+- `one-ie/CLAUDE.md § Workflow step kinds`

package/skills/writer/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: writer
+description: Write, edit, and improve any prose — blog posts, essays, articles, landing page copy, founder updates, LinkedIn posts, technical explanations, marketing emails, documentation, or any other written deliverable. Use this skill whenever the user asks to "write", "draft", "rewrite", "edit", "polish", "tighten", "make this clearer", "improve this copy", "fix my writing", or asks for help with anything that ends up as words on a page. Use it for short pieces (a single tweet, a paragraph) and long ones (a 2,000-word essay) alike. Use it even when the user has already drafted something and just wants feedback — the skill covers editing as much as it covers drafting.
+---
+
+# Writer
+
+A skill for producing prose that lands. The goal is writing that is clear, alive, and structurally sound — not "correct" in the schoolteacher sense, not bloated with adjectives, not LinkedIn-ese.
+
+This skill exists because most writing fails for the same handful of reasons: the writer didn't know who they were writing for, didn't lead with the strongest point, told instead of showed, padded with adjectives instead of facts, ignored how readers actually process sentences, and stopped at the first draft. Fix those six things and the prose becomes good. Fix them consistently and the prose becomes great.
+
+---
+
+## The core loop
+
+Every piece of writing — long or short — goes through this loop:
+
+1. **Understand the audience, medium, and goal** before writing a word.
+2. **Draft fast, without judgement.** Get the ideas down. Don't edit while drafting.
+3. **Cut.** Aim to halve the word count. Then halve again where possible.
+4. **Restructure.** Move the strongest point to the top. Reorder for flow.
+5. **Polish at the sentence level.** Apply the five questions (below).
+6. **Read it aloud.** A good sentence sounds good. If it stumbles, rewrite it.
+7. **Stop when it's done.** Don't pad.
+
+If time is short, skip steps 5 and 6 and ship. Steps 1–4 are non-negotiable.
+
+---
+
+## Step 0: Audience, medium, goal
+
+Before writing anything, answer four questions. If the user hasn't given you enough to answer them, ask. Don't guess.
+
+- **Audience.** Who is reading this? What do they already know? What do they care about? What language do they actually use? (A landing page for a Thai parent, a Slack message to a CTO, and a thread on Hacker News all need different sentences.)
+- **Medium.** Email, blog post, tweet, white paper, landing page, founder update, push notification? The medium dictates length, tone, and which rules are worth breaking.
+- **Mode.** Persuasive, explanatory, narrative, reference? A "how-to" reads differently from a "here's what I think."
+- **Goal.** What do you want the reader to do, feel, or believe after reading? If you can't state this in one sentence, you aren't ready to write.
+
+If the user's request is ambiguous (e.g. "write me something about X"), pick the most likely answers, state them inline as assumptions, and proceed. Don't stall on questions when good defaults exist.
+
+---
+
+## Step 1: Drafting
+
+When drafting, **do not edit**. Editing while drafting kills momentum and produces neither a good draft nor a good edit.
+
+- Start with the point you most want to make. Not the setup, not the throat-clearing, not "In today's fast-paced world…" — the point.
+- Write in your natural voice. If you're drafting for someone else, write in theirs. Read three things they've written first, then echo their rhythm.
+- Use placeholders for facts you'll need to check: `[stat: Q3 churn rate]`. Don't break flow to look things up.
+- It's fine for the first draft to be twice as long as the final. Cutting is easier than expanding.
+
+---
+
+## Step 2: Cutting (the highest-leverage step)
+
+Most writing is 30–70% too long. Cut anything that doesn't earn its place.
+
+**Cut these on sight:**
+
+- Adverbs that boost weak verbs ("walked quickly" → "hurried"; "very large" → "huge" or just a number).
+- Adjective stacks ("blazingly fast and incredibly efficient" → pick one, or replace with a fact).
+- Hedges that protect the writer rather than serve the reader ("I think maybe it could possibly be the case that…" → state the thing).
+- "In order to" → "to". "At this point in time" → "now". "Due to the fact that" → "because".
+- Throat-clearing openers: "I just wanted to say…", "It's worth noting that…", "In today's world…".
+- Empty intensifiers: "really", "very", "literally", "actually", "basically", "simply", "essentially".
+- Restating the question back at the reader ("That's a great question. The answer to whether X is Y is…").
+- Closing throat-clearing: "I hope this helps!", "At the end of the day…", "Hopefully that gives you a sense of…".
+
+**Cut whole sentences if:**
+
+- They restate something already said.
+- They explain a metaphor you just used (trust the reader).
+- They could be deleted without anyone noticing.
+
+**Diagnostic.** Read each paragraph and ask: if I deleted this paragraph, would the piece be worse? If no, delete it.
+
+---
+
+## Step 3: Show, don't tell
+
+This is the single biggest weakness in most writing — including most professional writing.
+
+**Telling** asserts. **Showing** demonstrates with specifics the reader can feel.
+
+**Bad (telling):**
+> Our app is blazingly fast and incredibly powerful.
+
+**Good (showing):**
+> The app cold-starts in 200ms. The competitor takes 4 seconds.
+
+**Bad (telling):**
+> She was nervous about the meeting.
+
+**Good (showing):**
+> She read the agenda four times on the elevator up.
+
+When you find an adjective doing heavy lifting ("amazing", "powerful", "innovative", "seamless", "robust"), replace it with the fact, number, or scene that earned the adjective. If you can't find that fact, the claim isn't real and shouldn't be in the piece.
+
+A drill that works: write the whole piece without adjectives. If it's still interesting, the content is good and you can add adjectives sparingly. If it's boring without them, the problem is the content, not the prose.
+
+---
+
+## Step 4: Structure (the part most advice skips)
+
+Structure is where good writing becomes great. Two frames cover most cases.
+
+### Frame 1: Reader expectations (Gopen & Swan)
+
+Readers have unconscious expectations about *where* information appears in a sentence. Match those expectations and prose becomes effortless to read without being dumbed down. Violate them and the reader works harder, gets less, and blames themselves.
+
+The rules:
+
+1. **Subject + verb close together.** Don't separate them with long parenthetical clauses. The reader holds their breath until the verb arrives.
+2. **Old information at the start of a sentence (topic position).** New information at the end (stress position). This is how you build flow: each sentence picks up where the last one left off, then introduces something new, which the next sentence picks up.
+3. **Whose story is this?** Put that person/thing in the topic position. If the sentence is about the customer, start with the customer. If it's about the product, start with the product.
+4. **Action lives in the verb.** "We made a decision to invest" → "We decided to invest." Nominalised verbs ("made a decision", "performed an analysis", "had a discussion") drain energy.
+5. **Context before novelty.** Tell the reader what frame to read the next thing in, then deliver the next thing.
+6. **Structural emphasis must match substantive emphasis.** If the most important point is at the end of the sentence in the stress position, good. If it's buried in a subordinate clause, fix it.
+
+### Frame 2: Lead with the strongest point
+
+Newer writers usually reach their strongest point around paragraph three. Emotional writers reach it at the end. Find yours and move it to the top.
+
+A practical edit: after drafting, scan for the sentence that made you most want to keep writing. That sentence is probably your real lede. Move it up. Delete everything before it that doesn't earn its place.
+
+For business writing, this often means the Pyramid Principle (Barbara Minto): state the conclusion first, then the supporting reasons, then the evidence. Readers can stop reading at any point and still take away the main thing.
+
+---
+
+## Step 5: The five sentence questions
+
+Once the structure is right, polish each sentence by asking, in order:
+
+1. **Does it say what I mean?** (Meaning is non-negotiable. Get this first.)
+2. **Can it be clearer?** (Includes brevity. Shorter is usually clearer.)
+3. **Does it match the tone of the piece?** (A formal sentence in a casual piece breaks the spell.)
+4. **Can it be more novel?** (Replace clichés. "At the end of the day", "move the needle", "low-hanging fruit", "game-changer" — all dead.)
+5. **Can it be more beautiful?** (Rhythm, sound, the play of the tongue. Read it aloud.)
+
+Start at the top. The moment an answer suggests a change, make it and start over from question 1. Under deadline you get to question 1 or 2. With time, you get to 5.
+
+---
+
+## Step 6: Read it aloud
+
+Move your lips. A sentence that stumbles when spoken stumbles when read silently — the reader just doesn't know why it feels off. Common problems this catches:
+
+- Sentences that are too long (you run out of breath).
+- Repeated word sounds at sentence boundaries ("…the system. The system…").
+- Awkward consonant clusters.
+- Rhythms that fight the meaning (a punchy idea in a meandering sentence).
+
+---
+
+## Tone defaults
+
+Unless the user specifies otherwise, default to:
+
+- **Short sentences.** Mix in longer ones for rhythm, but lean short.
+- **Concrete over abstract.** "Three customers cancelled this week" beats "we're seeing some churn signals."
+- **Active voice by default.** Passive is fine when the actor is unknown or genuinely irrelevant ("The server was rebooted overnight").
+- **Conversational over formal.** "Don't" not "do not", unless the piece is genuinely formal.
+- **Plain words over fancy ones.** "Use" not "utilise". "Help" not "facilitate". "About" not "regarding".
+- **Specific over general.** Names, numbers, places, dates.
+
+Avoid by default:
+
+- LinkedIn-ese. "I'm thrilled to announce", "humbled and honoured", "circle back", "synergies", "leverage" (as a verb), "thought leader", "ecosystem" used loosely.
+- Hype adjectives without facts: "incredible", "amazing", "revolutionary", "game-changing", "world-class", "best-in-class", "next-generation".
+- Em-dash overuse as a substitute for clear sentence structure. (One em-dash per paragraph max, usually fewer.)
+- Bullet points where prose would be clearer. Bullets are for genuinely list-shaped content (steps, options, criteria). Don't bullet ideas that connect to each other — write the connection.
+- Headers in short pieces. A 400-word post does not need three H2s.
+- Emoji unless the user uses them or the medium expects them.
+
+---
+
+## Common formats
+
+When the user asks for a specific format, these are the defaults. Adjust based on Step 0 (audience, medium, goal).
+
+### Blog post / essay
+
+- Open with the strongest point or a concrete scene. Not a definition. Not "In this post, I'll…".
+- One idea per paragraph.
+- Section headers only if the piece is long enough that a reader might want to skim or return to a section.
+- Close on a thought worth carrying away. Not "in conclusion". Not a summary of what you just said.
+
+### Landing page / marketing copy
+
+- Headline names the audience's problem or desired outcome in their words.
+- Subhead delivers the proof or specificity ("how").
+- Body shows, doesn't tell — facts, numbers, screenshots, named customers.
+- One clear call to action.
+- Cut every word that doesn't sell.
+
+**Pick one headline framework per page; don't mix.** The canon — ten templates,
+when each one fits, plus the specificity rule, the sensory rule, and the seven
+biases (anchoring, loss aversion, social proof, authority, reciprocity,
+scarcity, decoy) doing the persuasive work underneath — is in
+`references/copy-frameworks.md`. Read it before writing or rewriting any
+landing-page hero, pricing page, or feature section.
+
+Quick map of the ten:
+
+| # | Framework | When |
+|---|---|---|
+| 1 | JTBD — "{Product} helps {audience} {job} without {friction}" | Mature category, narrow buyer |
+| 2 | PAS — Problem · Agitate · Solve | Pain is felt but unsolved |
+| 3 | BAB — Before · After · Bridge | Category shift, transformation story |
+| 4 | Outcome + timeframe — "{Outcome} in {time}" | You can prove the speed |
+| 5 | Hard thing without pain — "{Outcome} without {usual cost}" | Differentiation = removal |
+| 6 | Plain truth — one declarative sentence | When the truth is good enough |
+| 7 | Numbered nouns — "{N} {things}. {result}." | Architecture / system products |
+| 8 | Category for audience — "The {category} for {audience}" | Carving a sub-category |
+| 9 | Dunford — "Unlike {alt}, {capability} so {value}" | Competitive market |
+| 10 | Real attributed quote | When the quote is *that* good |
+
+Two non-negotiable rules every headline passes:
+
+- **Specificity (Harry Dry):** if a competitor could put their logo on your
+  headline and have it still be true, rewrite. "Worn by supermodels in London
+  and dads in Ohio" only works for New Balance.
+- **Sensory:** concrete nouns are recalled +200% vs. abstract concepts. "Touch
+  ID signs every transaction" beats "industry-leading security model."
+
+### Founder update / investor email
+
+- Lead with the headline (what changed, what's working, what's broken).
+- Numbers up top. Story underneath.
+- Honest about problems. Investors trust founders who name the hard things.
+- End with specific asks if you have any.
+
+### LinkedIn / social post
+
+- First line earns the click to "see more". Make it a hook, not a setup.
+- Short paragraphs, often one sentence each (the format demands it).
+- One idea per post. Don't try to say three things.
+- No hashtag spam.
+
+### Email
+
+- Subject line: specific, not clever. ("Friday review — 3 decisions needed" beats "Quick check-in".)
+- First sentence states the purpose.
+- Asks are explicit and easy to act on.
+- Short. Almost always shorter than your first instinct.
+
+### Technical explanation / documentation
+
+- Lead with what the thing is and what it's for. Not the history.
+- Concrete examples before abstractions.
+- Code blocks and diagrams where they're clearer than prose.
+- Define jargon the first time it appears, or link to a definition.
+
+---
+
+## Editing someone else's draft
+
+When the user gives you a draft to improve:
+
+1. **Read it through once before changing anything.** Understand what they're trying to do.
+2. **Preserve their voice.** If they write punchy, stay punchy. If they write warm, stay warm. Your job is to make their writing better, not to make it sound like yours.
+3. **Identify the strongest sentence in the draft.** If it isn't near the top, that's usually the first fix.
+4. **Cut before you add.** Most drafts get better by 30% just from cutting.
+5. **Show the change, not just the result.** If the user pasted a paragraph, return the rewritten paragraph and a one-line note on what changed and why. They learn faster, and they can push back on changes they disagree with.
+6. **Don't over-correct.** If a sentence is fine, leave it. Constant tinkering loses the writer's trust.
+
+When the user asks for "feedback" rather than a rewrite, give feedback. Don't rewrite the whole thing unless they asked. Diagnose: what's working, what isn't, what one change would have the biggest effect.
+
+---
+
+## What to avoid
+
+- **Never use em dashes habitually.** They're a tic that signals AI-written prose. Use commas, full stops, or parentheses instead. One em-dash in a piece is fine; six is a tell.
+- **Never use "delve", "navigate" (as a metaphor), "tapestry", "landscape" (as a metaphor), "in the realm of", "it's important to note", "in conclusion", "in summary".** These are AI-prose tells. They're also just bad writing.
+- **Never write "As an AI…" or refer to the writing process from inside the piece** unless explicitly asked to.
+- **Never pad to hit a word count.** If the piece is done at 300 words and the user asked for 500, return 300 and say so. Padding is worse than under-delivering.
+- **Never use "elevate", "unlock", "empower", "transform", "supercharge", "revolutionise"** in marketing copy unless quoting someone.
+- **Never start a piece with a dictionary definition.** It's the laziest opening in writing.
+
+---
+
+## When to ask vs when to proceed
+
+**Proceed without asking when:**
+
+- The user pasted a draft and asked you to "improve" or "tighten" it. Just do it.
+- The user asked for a specific deliverable in a specific format ("write a 200-word LinkedIn post about X"). Ship the post.
+- The audience and goal are obvious from context.
+
+**Ask first when:**
+
+- The user said "write me something about X" with no medium or audience specified, and the choice meaningfully changes the output.
+- You'd need to invent significant facts to write the piece (numbers, names, customer quotes).
+- The user's voice matters and you have no examples of it.
+
+When in doubt, write the piece with stated assumptions ("Assuming this is for a developer audience and goes on your blog…") rather than stalling on questions.
+
+---
+
+## A note on length
+
+Match length to the job. A great tweet is 30 words. A great founder update is 400. A great essay might be 3,000. None of these are inherently better than the others.
+
+But: when in doubt, shorter. Almost no one ever wishes a piece of writing were longer.
+
+---
+
+## Project-specific voice
+
+Two voice documents layer on top of this skill. Read both before writing anything here.
+
+**Personal essays, blog posts, tech pieces, opinion writing:**
+[`text/writing-style-guide.md`](../../../../text/writing-style-guide.md) — Anthony's
+personal writing style. Dry, sardonic, technically grounded. The sensibility
+(does this tool serve the work, or has it started serving itself?), the
+typography fingerprint (trailing ` …`, the em-dash ration, scare-quotes,
+capitalized Concepts), the sentence rhythm (punch / carrier / escalating list),
+and the recurring beats (received-wisdom turn, forensic descent, two-camps
+dismissal). This is the default voice for any personal piece. Apply it always.
+
+**Marketing, product, and landing-page copy:**
+[`/.claude/product-marketing.md`](../../product-marketing.md) — ONE's brand voice.
+Audience (CEOs + engineers), the speed/ease/simplicity thesis, banned vocabulary,
+headline patterns, and the data rule. Layers on top of the personal voice for
+anything that ships as ONE copy.
+
+---
+
+## Reference files
+
+- `text/writing-style-guide.md` — **Always read.** Anthony's personal writing voice: sensibility, typography fingerprint, sentence rhythm, recurring beats, vocabulary bank, anti-patterns, worked examples.
+- `references/anti-patterns.md` — A longer catalogue of clichés, AI-prose tells, and corporate jargon to avoid, with replacements. Read this when editing marketing or corporate copy where the user wants to sound less like a press release.
+- `references/voice-matching.md` — How to read a writer's voice from sample text and match it. Read this when ghostwriting or editing on someone else's behalf.
+- `references/structures.md` — Concrete templates for common pieces (essay openings, founder updates, landing page sections, cold emails). Read this when the user asks for a format you want to handle well.
+- `references/copy-frameworks.md` — The canon: ten headline frameworks (JTBD, PAS, BAB, outcome+timeframe, hard-thing-without-pain, plain truth, numbered nouns, category-for-audience, Dunford positioning, attributed quote) with when-to-use, examples, traps; the specificity and sensory rules; the seven biases (anchoring, loss aversion, social proof, authority, reciprocity, scarcity, decoy) and which frameworks recruit which. Read this when writing or rewriting landing pages, pricing pages, hero sections, or any headline that has to convert.
+
+These are loaded only when relevant. Don't read them for every task.
+
+---
+
+## The thing nobody can teach
+
+Live a life worth writing about. Voice comes from somewhere. The best writing in the world is animated by the writer's actual thinking, actual taste, actual stake in the subject. This skill can sharpen prose. It can't manufacture conviction. When the user has something real to say, get out of their way and help them say it cleanly.