@zeix/cause-effect 1.0.0 → 1.0.1

package/skills/tech-writer/references/tone-guide.md

@@ -0,0 +1,189 @@
+<overview>
+Writing tone, register, and conciseness rules for each document maintained by the tech-writer
+skill. Violating the tone is as wrong as a factual error — each document has a distinct
+primary reader and serves a distinct purpose.
+</overview>
+
+<shared_rules>
+These rules apply to every document without exception:
+
+- **Concise over comprehensive.** Every sentence must add information the reader needs.
+  Cut throat-clearing, transitional padding, and restatements of what the code already
+  shows.
+- **Technically accurate over reassuring.** Do not soften edge cases, paper over
+  constraints, or omit behavior that is surprising but correct.
+- **No changelog language in documentation.** Documents state current truth. Never write
+  "previously", "as of version X", "we changed", or "now supports". Those belong in
+  CHANGELOG.md.
+- **No meta-commentary.** Do not write "This section explains…" or "See below for…".
+  Say the thing directly.
+- **Backtick all code.** Every API name, flag, file name, type name, option key, and
+  shell command is wrapped in backticks, even mid-sentence.
+</shared_rules>
+
+<README>
+**Primary audience:** Developers integrating `@zeix/cause-effect` into a project.
+They know TypeScript and have used reactive libraries before.
+
+**Register:** Instructional. Direct address ("use `createTask` when…"). Present tense.
+Active voice. Short sentences in prose; examples do the heavy lifting.
+
+**Structure rules:**
+- Each `### SignalType` section: one short paragraph describing what the signal is for,
+  then the signature, then options, then example(s). Description first — don't open with
+  the signature.
+- Options tables: one row per option. "Description" column is one line; if it needs more,
+  the option is complex enough to warrant a prose sentence below the table instead.
+- Examples: realistic, not trivial. Show actual usage patterns, not `const x = createState(0)`.
+  Prefer examples that demonstrate the signal's distinctive behavior.
+
+**What to cut:**
+- Explanations of TypeScript concepts the reader already knows
+- Warnings about things the type system already prevents
+- Motivational framing ("This is useful when you need to…")
+</README>
+
+<GUIDE>
+**Primary audience:** Developers migrating from React, Vue, or Angular who want to
+understand where this library's concepts map to — and diverge from — what they already know.
+
+**Register:** Comparative and educational. Assumes framework fluency; never assumes
+knowledge of this library. Uses "if you've used X, this is like Y, except…" framing.
+Approachable but never condescending.
+
+**Structure rules:**
+- Comparisons must be specific. Name the exact React hook, Vue function, or Angular
+  decorator being compared. Vague comparisons ("like in other frameworks") add no value.
+- Divergences get more space than similarities. The reader can infer the familiar parts;
+  the non-obvious differences are why this section exists.
+- Code examples: show both the framework equivalent and the cause-effect version side by
+  side when it aids comparison. Otherwise, cause-effect only.
+
+**What to cut:**
+- Explanations of how React/Vue/Angular work internally — assume the reader knows
+- Repetition of content already in README.md — GUIDE.md is conceptual, not a reference
+- Sections that say "this is the same as in other frameworks" without adding nuance
+</GUIDE>
+
+<ARCHITECTURE>
+**Primary audience:** Contributors to the library and AI agents that need to understand
+internals to implement or review changes correctly.
+
+**Register:** Technical and precise. Third person, present tense. Implementation details
+are expected and welcome. Internal function names, type names, flag names, and field names
+are used freely without definition — this document assumes the reader has the source open.
+
+**Structure rules:**
+- Describe mechanisms, not intentions. Not "this enables efficient updates" but "when
+  `propagate()` marks a node `FLAG_CHECK`, downstream nodes call `refresh()` before
+  deciding whether to recompute".
+- Pseudocode and inline type definitions are appropriate when they make a structure clearer
+  than prose would. Match the actual source types exactly — do not simplify.
+- Subsection depth: use the existing pattern (##, ###). Do not add new heading levels.
+
+**What to cut:**
+- Motivational framing ("The design optimizes for…") — state the mechanism, not the goal
+- Public API description — that belongs in README.md
+- Any sentence that could be replaced by reading the source directly
+</ARCHITECTURE>
+
+<CLAUDE_MD>
+**Primary audience:** Claude (this model) at inference time. Every token has a cost.
+
+**Register:** Terse, declarative, maximally dense. No hand-holding. No transitions.
+Bold key terms. Bullet lists over prose. Code examples only when the correct pattern is
+non-obvious from the statement.
+
+**Structure rules:**
+- Non-obvious behavior entries follow a strict three-part structure:
+  1. **Bold statement** of the behavior — one sentence, declarative, specific.
+  2. Implication or consequence — one or two sentences maximum.
+  3. Code example — only if the correct pattern cannot be inferred from the statement.
+     Use before/after style (bad comment + good comment) only when the contrast is the point.
+- The bar for "non-obvious": an experienced reactive developer would not predict this
+  behavior from the public API alone. If they would, it does not belong here.
+- Internal names (`FLAG_CHECK`, `activeSink`, `trimSources`) are appropriate — Claude
+  can cross-reference ARCHITECTURE.md.
+
+**What to cut:**
+- Any sentence that restates what the bold statement already said
+- Explanations of standard reactive concepts (memoization, lazy evaluation, dependency tracking)
+- "Note that…", "Keep in mind…", "Be aware that…" — state it directly
+- Examples that illustrate obvious correct usage; examples only for non-obvious patterns
+</CLAUDE_MD>
+
+<copilot_instructions>
+**Primary audience:** GitHub Copilot during code generation. The document drives what
+Copilot suggests as it completes function calls, option objects, and type annotations.
+
+**Register:** Structured and pattern-oriented. Headers create anchors Copilot uses to
+locate relevant context. Code blocks are generation templates — they must be complete,
+compilable, and idiomatic.
+
+**Structure rules:**
+- Code patterns must compile against the current `index.ts`. Copilot generates from these
+  literally — a wrong parameter name or stale option key will be reproduced in generated code.
+- Signal type descriptions: one line each in the format
+  `**Name** (\`createName\`): what it is and its key behavioral trait.`
+- Do not use narrative prose in list items — use fragments that complete a pattern, not
+  sentences that explain one.
+
+**What to cut:**
+- Explanatory prose around code patterns — the pattern is self-documenting
+- Options or parameters that are rarely used and not needed for the common case
+- Duplication between sections (e.g. do not describe `createTask` in both "Signal Types"
+  and again identically in "Common Code Patterns")
+</copilot_instructions>
+
+<REQUIREMENTS>
+**Primary audience:** Stakeholders, contributors, and future maintainers who need to
+understand the library's purpose and boundaries. This document is read infrequently and
+must remain accurate over many versions.
+
+**Register:** Formal, strategic, timeless. Third person. Noun phrases over verb phrases
+where possible ("The library is deliberately not a framework" rather than "We decided not
+to make this a framework"). No version-specific language except in "Stability".
+
+**Structure rules:**
+- Tables state facts as rows — they do not tell a story. Each row is self-contained.
+- "Non-Goals" entries are one bold heading + one sentence. The heading names the thing
+  that is out of scope; the sentence says why or what to do instead. No more.
+- "Stability" is the only section that may reference specific version numbers. All other
+  sections describe the library as it is, not how it got there.
+
+**What to cut:**
+- Rationale for decisions that were obvious or uncontroversial — if it needs defending,
+  add one sentence; otherwise state the fact
+- Historical context ("this was added because…")
+- Implementation detail — REQUIREMENTS.md describes goals, not mechanisms
+</REQUIREMENTS>
+
+<jsdoc>
+**Primary audience:** Developers reading function signatures in an IDE or in generated
+API documentation. They see the JSDoc in a tooltip or a docs page alongside the TypeScript
+signature.
+
+**Register:** Brief, typed, precise. One-line summaries. No narrative. Fragments are
+acceptable if they read naturally as a tooltip.
+
+**Structure rules:**
+- Summary line: one line. Describes what the function does, not what it is.
+  "Creates a mutable reactive signal." not "A factory function for State signals."
+- `@param` tags: one line each. Describe semantics and constraints, not the TypeScript
+  type (the type is already visible in the signature). For options objects, document only
+  options whose behavior is non-obvious.
+- `@returns`: one line. What is returned and any non-obvious guarantee
+  (e.g. "Always non-nullish per `T extends {}`").
+- `@throws`: only for errors that can occur in correct, non-erroneous usage. Do not
+  document programmer-error throws (`RequiredOwnerError`, `InvalidCallbackError`,
+  `CircularDependencyError`) — they indicate a coding mistake, not a handled condition.
+- `@example`: only if the usage pattern is so non-obvious that a developer would misuse
+  the function without it. Examples live primarily in README.md.
+
+**What to cut:**
+- `@param type` annotations — TypeScript already shows the type
+- JSDoc that restates the TypeScript signature in prose
+- Generic descriptions that would apply to any function ("Creates and returns a…")
+- Multi-paragraph descriptions — if it needs that much explanation, the API design may
+  need review
+</jsdoc>

package/skills/tech-writer/workflows/consistency-review.md

@@ -0,0 +1,98 @@
+<required_reading>
+1. references/document-map.md — full index of documents, their scope, and what to verify in each
+</required_reading>
+
+<process>
+## Step 1: Read the source of truth
+
+Read `index.ts` for the complete public API surface. Read `src/graph.ts` for the graph engine
+and internal node shapes. Note the current version in `package.json`.
+
+These are the ground truth. Every document is checked against them, not against each other.
+
+## Step 2: Check each document in turn
+
+Work through the documents in this order. For each one, read the current document alongside
+the relevant source, then record findings before moving to the next.
+
+### REQUIREMENTS.md
+- Signal type table (9 types) matches the exports in `index.ts`
+- Bundle size targets still reflect current library scope
+- Non-goals do not contradict any feature that has since been added
+- Stability section reflects the current version and release status
+
+### ARCHITECTURE.md
+- Concrete Node Types table matches the node shapes in `src/graph.ts`
+- Node Field Mixins table matches `SourceFields`, `SinkFields`, `OwnerFields`, `AsyncFields`
+  as defined in `src/graph.ts`
+- Flag names (`FLAG_CLEAN`, `FLAG_CHECK`, `FLAG_DIRTY`, `FLAG_RUNNING`) match `src/graph.ts`
+- Each signal type subsection describes the correct internal composition and lifecycle
+- No subsection references a removed node type, flag, or function
+
+### CLAUDE.md
+- Internal Node Shapes block matches `src/graph.ts`
+- `activeOwner` / `activeSink` semantics description is accurate
+- Each non-obvious behavior entry is still accurate for the current implementation
+- Mental model analogy covers all 9 signal types
+
+### .github/copilot-instructions.md
+- Signal Types list covers all 9 signal types with accurate one-line descriptions
+- Key Files Structure lists all current `src/` files
+- Code patterns in "Common Code Patterns" compile against current `index.ts`
+  (check factory signatures, option names, parameter order)
+- API Design Principles reflect current conventions
+
+### README.md
+- Every factory function exported from `index.ts` has a documented `### SignalType` section
+- All option names, parameter names, and types match current signatures
+- Code examples in the API section use current factory signatures
+- "Choosing the Right Signal" table covers all 9 signal types
+- "Advanced Usage" examples use current API
+
+### GUIDE.md
+- "The Familiar Core" table references current factory function names
+- "What Works Differently" sections describe current behavior
+- "Beyond the Basics" signal type sections are accurate and use current API
+- Code examples compile against current `index.ts`
+
+### JSDoc in src/ (spot-check)
+- Read `src/nodes/state.ts`, `src/nodes/memo.ts`, and `src/nodes/effect.ts`
+- Verify that `@param` tags match current parameter names and types
+- Verify that `@returns` descriptions are accurate
+- Flag any JSDoc that describes removed or renamed options
+
+## Step 3: Compile findings
+
+Produce a structured report before making any edits:
+
+```
+## Consistency Review — [date]
+
+### Accurate (no changes needed)
+- REQUIREMENTS.md: consistent
+- ...
+
+### Gaps found
+- ARCHITECTURE.md, "Concrete Node Types": [specific claim] is outdated — [what is correct]
+- README.md, "### Task": option `abort` renamed to `signal` in current index.ts
+- ...
+```
+
+Be specific: name the document, section, and the exact discrepancy. Do not summarize vaguely.
+
+## Step 4: Confirm before editing
+
+Present the report and ask: **"Shall I apply all of these updates, or would you like to
+review and select?"**
+
+Do not make any edits until explicitly confirmed. If the user confirms all, follow the
+relevant per-document workflow for each gap identified. If they select a subset, update
+only those.
+</process>
+
+<success_criteria>
+- All seven documents checked against current source (`index.ts`, `src/graph.ts`)
+- Findings reported as a structured list with specific document, section, and discrepancy
+- No edits made before confirmation
+- After confirmation, each gap resolved using the appropriate per-document workflow
+</success_criteria>

package/skills/tech-writer/workflows/update-after-change.md

@@ -0,0 +1,65 @@
+<required_reading>
+1. references/document-map.md — map the change type to affected documents
+</required_reading>
+
+<process>
+## Step 1: Understand the change
+
+Inspect the diff against the main branch:
+
+```bash
+git diff main..HEAD -- src/ index.ts
+```
+
+If no diff is available, ask the user to describe what changed.
+
+## Step 2: Classify the change
+
+Identify which of the following change types apply — more than one may apply:
+
+| Change type | Examples |
+|---|---|
+| **New public API** | New factory function, new export, new type in `index.ts` |
+| **Changed public API** | Modified signature, new option, renamed parameter, changed return type |
+| **Removed public API** | Removed export, removed option, removed type |
+| **New or changed non-obvious behavior** | Graph semantics, propagation edge case, ownership subtlety |
+| **Internal implementation change** | Graph engine logic, flag values, node shapes, propagation algorithm |
+| **Vision or scope change** | New design principle, changed audience, new constraint or non-goal |
+
+## Step 3: Determine affected documents
+
+Use this table to identify which documents need updating:
+
+| Change type | JSDoc | ARCHITECTURE.md | CLAUDE.md + copilot | README.md | GUIDE.md | REQUIREMENTS.md |
+|---|---|---|---|---|---|---|
+| New public API | ✓ | ✓ | ✓ | ✓ | ✓ if conceptually new | ✓ signal type table only |
+| Changed public API | ✓ | if node shape changed | ✓ if behavior changes | ✓ | ✓ if affects mental model | ✗ |
+| Removed public API | ✓ | ✓ if structural | ✓ | ✓ | ✓ if was documented | ✗ |
+| New/changed non-obvious behavior | ✗ | ✓ if graph-level | ✓ | ✓ if affects usage pattern | ✗ | ✗ |
+| Internal implementation change | ✗ | ✓ | ✓ | ✗ | ✗ | ✗ |
+| Vision or scope change | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
+
+## Step 4: Update affected documents in order
+
+Follow the corresponding workflow for each affected document. Always work in this order — each layer informs the next:
+
+1. **JSDoc** (`src/`) — closest to code; establishes precise wording
+   → workflows/update-jsdoc.md
+2. **ARCHITECTURE.md** — internal structure; must be consistent with source
+   → workflows/update-architecture.md
+3. **CLAUDE.md + copilot-instructions.md** — agent docs; must be consistent with architecture
+   → workflows/update-agent-docs.md
+4. **README.md + GUIDE.md** — public docs; must be consistent with API and agent docs
+   → workflows/update-public-api.md
+5. **REQUIREMENTS.md** — only if scope changed
+   → workflows/update-requirements.md
+
+Skip any document not identified as affected in Step 3.
+</process>
+
+<success_criteria>
+- Change type(s) correctly identified from the diff or description
+- Only affected documents updated — no speculative edits
+- Documents updated in the prescribed order
+- Each document follows its tone guide
+</success_criteria>

package/skills/tech-writer/workflows/update-agent-docs.md

@@ -0,0 +1,77 @@
+<required_reading>
+1. references/document-map.md — CLAUDE.md and copilot-instructions.md sections
+2. references/tone-guide.md — agent-docs tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the source
+
+Read the relevant `src/nodes/*.ts` file(s) and `src/graph.ts` if the change touches graph
+semantics. Read the current `CLAUDE.md` and `.github/copilot-instructions.md` in full.
+Never update agent docs from memory — subtle inaccuracies are worse than gaps.
+
+## Step 2: Update CLAUDE.md
+
+CLAUDE.md is the inference-time reference for Claude. It covers the mental model, internal
+node shapes, and non-obvious behaviors. Token cost is real — every line must earn its place.
+
+**Mental model section**
+- Update the spreadsheet-cell analogy if a new signal type is added. One line per type,
+  consistent with the existing terse style.
+
+**Internal Node Shapes section**
+- Update the node shape table if `SourceFields`, `SinkFields`, `OwnerFields`, or `AsyncFields`
+  changed in `src/graph.ts`, or if a new node type was added.
+- Update the `activeOwner` / `activeSink` description if their semantics changed.
+
+**Non-Obvious Behaviors section**
+- Add an entry when a behavior is counterintuitive enough that a competent developer would
+  not predict it from the public API alone.
+- Remove or correct an entry when a previously non-obvious behavior has changed.
+
+Each entry must follow this structure exactly:
+1. **Bold statement** of the behavior — one sentence, declarative.
+2. One or two sentences of implication. No padding.
+3. A code example only if the correct pattern is non-obvious from the statement alone.
+   Use the existing before/after style where it adds clarity.
+
+Do NOT add entries for behavior that is obvious from the type signatures or from standard
+reactive library conventions. The bar is: would an experienced reactive developer be
+surprised by this?
+
+## Step 3: Update .github/copilot-instructions.md
+
+copilot-instructions.md drives GitHub Copilot's code generation. Accuracy of the code
+patterns is critical — Copilot uses these as generation templates.
+
+**Core Architecture section**
+- Update the node type list if a new node type was added or an existing one changed role.
+- Update the flag list (`FLAG_CLEAN`, `FLAG_CHECK`, `FLAG_DIRTY`, `FLAG_RUNNING`) if flags
+  were added, renamed, or removed.
+
+**Signal Types section**
+- Add a one-line entry for each new signal type: `**Name** (\`createName\`): description`.
+- Update the description of any signal type whose behavior or options changed.
+
+**Key Files Structure section**
+- Add a new line if a new source file was added.
+
+**Common Code Patterns section**
+- This is the highest-value section. Update the code block under "Creating Signals" to
+  reflect any changed factory signatures or new signal types.
+- Patterns must compile against the current API. Verify each pattern against `index.ts`.
+- Add a new pattern block only if the new usage cannot be inferred from existing patterns.
+
+**Coding Conventions / API Design Principles sections**
+- Update only if a new convention was established or an existing one changed.
+</process>
+
+<success_criteria>
+- Source file(s) read before any edits
+- CLAUDE.md non-obvious behavior entries accurate, terse, and consistently structured
+- CLAUDE.md node shapes consistent with `src/graph.ts`
+- copilot-instructions.md code patterns compile against the current `index.ts`
+- Both documents remain concise — no explanatory padding
+- Tone matches references/tone-guide.md: terse and direct for CLAUDE.md,
+  structured and pattern-focused for copilot-instructions.md
+</success_criteria>

package/skills/tech-writer/workflows/update-architecture.md

@@ -0,0 +1,61 @@
+<required_reading>
+1. references/document-map.md — ARCHITECTURE.md section
+2. references/tone-guide.md — architecture tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the source of truth
+
+Read `src/graph.ts` in full. Read any changed `src/nodes/*.ts` file(s). ARCHITECTURE.md
+describes internals — accuracy requires reading the actual implementation, not inferring
+from public API or documentation.
+
+## Step 2: Identify what changed architecturally
+
+Changes that warrant an ARCHITECTURE.md update:
+
+| Changed | Section to update |
+|---|---|
+| Edge structure (`Edge` type fields) | Core Data Structures → Edges |
+| Node field mixins (`SourceFields`, `SinkFields`, etc.) | Core Data Structures → Node Field Mixins |
+| Concrete node types or their composition | Core Data Structures → Concrete Node Types |
+| `activeSink` protocol or `link()`/`trimSources()`/`unlink()` | Automatic Dependency Tracking |
+| Flag values or `propagate()`/`refresh()`/`setState()` | Change Propagation |
+| `batch()`/`flush()` or effect scheduling | Effect Scheduling |
+| `activeOwner`, cleanup storage, `createScope()` | Ownership and Cleanup |
+| New or changed signal type | Signal Types → relevant subsection |
+
+Do NOT update sections that remain accurate. If only `src/nodes/memo.ts` changed, only
+the Memo subsection under "Signal Types" needs editing.
+
+## Step 3: Update the affected section(s)
+
+For each affected section:
+
+1. Re-read the current section text alongside the new source.
+2. Identify specific claims that are now wrong or incomplete.
+3. Make the minimal edit that makes those claims accurate.
+
+**Node shape changes:** Update the table in "Concrete Node Types" and the corresponding
+mixin table if field composition changed. If a new field mixin was added, add a row.
+
+**Propagation or flag changes:** Update the prose description and any pseudocode or
+inline code that references the changed behavior. If flag names changed, update every
+occurrence.
+
+**New signal type:** Add a new subsection under "Signal Types" following the existing
+pattern: one paragraph describing the node's role in the graph, its internal composition,
+and any non-obvious lifecycle behavior (watched activation, ownership, async cancellation).
+Do not duplicate the public API — describe the internal mechanics only.
+
+**Removed signal type:** Remove its subsection. Check for cross-references in other
+subsections.
+</process>
+
+<success_criteria>
+- `src/graph.ts` read in full before any edits
+- Only sections affected by the change were modified
+- Node shapes, flag names, and function descriptions match the current source exactly
+- New signal type subsection follows the structure and depth of existing subsections
+- Tone is technical and internal-facing per references/tone-guide.md
+</success_criteria>

package/skills/tech-writer/workflows/update-jsdoc.md

@@ -0,0 +1,72 @@
+<required_reading>
+1. references/tone-guide.md — jsdoc tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the implementation first
+
+Read the full source file being updated. JSDoc must describe what the code actually does —
+not what it should do, not what the previous version did.
+
+For public API changes, also read `index.ts` to confirm the exported signature matches
+the implementation.
+
+## Step 2: Identify which JSDoc blocks need updating
+
+A JSDoc block needs updating when any of the following changed:
+
+- The function signature (parameter added, removed, renamed, or retyped)
+- The return type or return value semantics
+- A thrown error condition that a caller must handle
+- The function no longer exists (remove the block with the function)
+
+Do NOT update JSDoc blocks that remain accurate. Read each existing block against the
+current implementation before deciding whether to edit it.
+
+## Step 3: Write or update the JSDoc block
+
+Follow this structure for all public API functions:
+
+```typescript
+/**
+ * One-line summary. No period if it reads as a fragment; period if it reads as a sentence.
+ *
+ * Second paragraph only if the one-liner is genuinely insufficient — e.g. a non-obvious
+ * constraint or a behavioral guarantee that cannot fit on one line. Omit otherwise.
+ *
+ * @param name - What it is. Include constraints (`T extends {}`, valid range, allowed
+ *   values). One line per param; wrap only if a constraint needs explaining.
+ * @param options - Options object, if present. Document only options that are non-obvious;
+ *   skip `equals` and `guard` unless the signal's default behavior for them is unusual.
+ * @returns What is returned and any guarantee about its value (e.g. "Always non-nullish").
+ */
+```
+
+**Constraints on length:**
+- Summary line: one line, no exceptions.
+- `@param` entries: one line each unless a constraint genuinely requires a second.
+- No `@example` blocks — examples live in `README.md`. Add one only if the usage pattern
+  is so non-obvious that a developer would misuse the function without it.
+- No `@throws` unless the error can occur in correct, non-erroneous usage (e.g.
+  `UnsetSignalValueError` on `Sensor.get()` before first value). Do not document
+  programmer-error throws (`RequiredOwnerError`, `InvalidCallbackError`, `CircularDependencyError`).
+
+**Type annotations in JSDoc:**
+- Do NOT repeat TypeScript types in `@param` or `@returns` tags. TypeScript already
+  enforces them. Only describe semantics, not types.
+
+## Step 4: Check consistency across the file
+
+After updating, scan the rest of the file for any JSDoc that cross-references the changed
+function or type. Update those references if they are now stale.
+</process>
+
+<success_criteria>
+- Source file read in full before any edits
+- Every updated block has a one-line summary
+- No `@example` blocks added unless usage is genuinely non-obvious
+- No `@throws` for programmer-error conditions
+- TypeScript types not duplicated in JSDoc prose
+- Updated blocks compile without JSDoc-related errors
+- Unchanged blocks left untouched
+</success_criteria>

package/skills/tech-writer/workflows/update-public-api.md

@@ -0,0 +1,59 @@
+<required_reading>
+1. references/document-map.md — README.md and GUIDE.md sections
+2. references/tone-guide.md — public-api and guide tone rules
+</required_reading>
+
+<process>
+## Step 1: Read the source of truth
+
+Read `index.ts` for the current public API surface. Read the relevant `src/nodes/*.ts`
+file(s) for any changed signal type. Do this before opening either document.
+
+## Step 2: Update README.md
+
+README.md is the authoritative public API reference. Make targeted edits only:
+
+**New signal type**
+- Add a `### SignalType` section under `## API` with: factory signature, all options, and
+  at least one realistic example showing normal usage.
+- Add the type to the "Choosing the Right Signal" table with a one-line description.
+- If the type participates in ownership or has a `watched` lifecycle, add an example to
+  "Advanced Usage → Resource Management".
+
+**Changed option or signature**
+- Update the relevant `### SignalType` section. Update the example if the old pattern no
+  longer compiles or no longer represents idiomatic usage.
+- If the change is a rename or a breaking type change, note the migration inline under the
+  parameter description, not in a separate section.
+
+**Removed API**
+- Remove all mentions. Check: the API section, "Choosing the Right Signal", "Advanced Usage",
+  and any cross-references in other signal type sections.
+
+**New or changed behavior**
+- Update the description in the relevant section. If the behavior is subtle, add or update
+  an example. If it is an advanced pattern, add to "Advanced Usage".
+
+## Step 3: Update GUIDE.md
+
+GUIDE.md explains the library through the lens of developers migrating from React, Vue,
+or Angular. Update it only when the change affects the conceptual picture:
+
+- **"The Familiar Core" table** — update if a core factory name changes.
+- **"What Works Differently"** — update if a fundamental behavioral contract changes
+  (e.g. synchronous vs. async execution, nullability rules, ownership model).
+- **"Beyond the Basics"** — update if a new signal type is added, or if a major signal
+  type changes significantly enough that its comparative explanation is wrong.
+
+Do NOT add every option change or minor signature tweak to GUIDE.md. Only update it when
+a developer's existing mental model from another framework would now lead them astray.
+</process>
+
+<success_criteria>
+- `index.ts` read before any edits were made
+- README.md accurately reflects the current public API: all factories documented, all
+  options current, all examples valid
+- GUIDE.md updated only where the conceptual picture for framework migrants changed
+- Both documents follow their respective tones from references/tone-guide.md
+- No sections rewritten beyond what the change requires
+</success_criteria>