Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Reword explainer writing guidance and mode rules in Archify's own terms

tt-a1i3688b5519189
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 14a5ff94..306a5a52 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -19,8 +19,8 @@ For a native diagram of a real codebase, read [Repository authoring](references/
- When the user asks to draw or visualize a system, flow, schema or history, use a native diagram and the Type router.
- Use `explainer` when the user asks for the answer as a page: a page, one page, an explainer, something to share (“做成一页”, “用页面讲”, “answer with a page”). Without such a request, answer in text or draw the requested diagram. A page made on request ends its reply with the one-line mode offer under Output.
-- A rules line in context changes this. `[archify explainer: proactive]`: also make a page, unasked, for an explanation, comparison, trade-off, decision, diagnosis, review or plan that needs a table, steps or several sections. `[archify explainer: always-on]`: attach a small page (2–4 panels) to every reply that gives a conclusion, rendered without opening, with the link last. `[archify explainer: on-demand]`: only when asked, and never offer a mode.
-- In every mode, small talk, a one- or two-sentence answer, pure command output and requests for plain text stay text.
+- A rules line in context changes this. `[archify explainer: proactive]`: also make a page, unasked, for an explanation, comparison, trade-off, decision, diagnosis, review or plan that needs a table, steps or several sections. `[archify explainer: always-on]`: every reply that reaches a conclusion also gets a compact page of at most four panels, delivered without opening it, its link closing the reply. `[archify explainer: on-demand]`: only when asked, and never offer a mode.
+- In every mode a page needs a conclusion with some structure behind it: chat, one-line answers, raw command output and text-only requests get none.
- For `explainer`, read [Explainer authoring](references/explainer-authoring.md) for its conclusion, reasons, scope, board layout and optional native diagrams. Write the complete draft, then run `finalize explainer` for validation, atomic delivery and artifact checks. Use panel patch for local content revisions.
## Existing candidate handoff
diff --git a/archify/explainer/writing.mjs b/archify/explainer/writing.mjs
index fed1ebdc..a534249f 100644
--- a/archify/explainer/writing.mjs
+++ b/archify/explainer/writing.mjs
@@ -10,7 +10,7 @@ const RULES = [
{id: 'cliche', pattern: /赋能|抓手|全方位|多维度|深度融合|至关重要|不可或缺|一站式|底层逻辑|\b(?:at the end of the day|in today[’']s fast-paced world|unlock the full potential|game[- ]changer|cutting[- ]edge|seamless(?:ly)?|delve into)\b/giu,
reason: 'This stock phrase gives little information about the concrete outcome.', example: '赋能业务 → 让客服查到订单状态; seamless → name what no longer needs a manual step', fix: 'Replace the stock phrase with the specific action or outcome the reader needs.'},
{id: 'filler', pattern: /下面我(?:来|将)|接下来我(?:来|将)|让我(?:们)?来|总的来说|综上所述|总而言之|值得注意的是|众所周知|毋庸置疑|希望(?:这)?(?:对你|对您)有(?:所)?帮助|如有疑问|\b(?:here is an overview|let[’']s (?:dive|take a look)|in conclusion|in summary|it is worth noting that|as we all know|i hope this helps)\b/giu,
- reason: 'Opening, closing or signposting filler delays the facts.', example: '综上所述,选 A → 选 A; In summary, use A → Use A', fix: 'Delete the phrase and start with the fact; the page ends when the facts end.'},
+ reason: 'Opening, closing or signposting filler delays the facts.', example: '综上所述,选 A → 选 A; In summary, use A → Use A', fix: 'Delete the phrase; open with the claim and stop after the last supported point.'},
{id: 'vague-quantity', pattern: /大量(?:请求|用户|数据)|很多(?:请求|用户|数据)|若干|尽快|\b(?:many users|a large number of requests|significantly faster|as soon as possible)\b/giu,
reason: 'The quantity or comparison lacks a stated bound or measurement.', example: '大量请求 → 写明已知请求量或说明未测量;尽快 → 写明期限; significantly faster → give the measured comparison or say it is unmeasured', fix: 'Add a supported quantity, range, deadline or comparison basis; when unknown, state that it is unmeasured. Do not invent a number.'},
{id: 'number-boundary', pattern: /(?<=\d\s*(?:个|次|秒|天|分钟|小时|倍|人|条|项|%|ms|MB|GB|KB|QPS)?\s*)(?:以上|以下|以内)/gu,
diff --git a/archify/references/explainer-authoring.md b/archify/references/explainer-authoring.md
index 7a6a8aee..37185101 100644
--- a/archify/references/explainer-authoring.md
+++ b/archify/references/explainer-authoring.md
@@ -85,16 +85,16 @@ A small answer gets a small page: the conclusion plus one or two panels. A how-i
## Writing
-Every sentence gives the reader one fact they need. Write in the user's language.
+Write for a reader who will act on the page and may check it. Use the user's language.
-- Start with the fact. The title asks the question, the conclusion answers it, and the page ends when the facts end.
+- The conclusion is read first; every panel after it supports, qualifies or applies it. Stop once nothing is left to support.
- Cover what the reader needs to act on the answer: the mechanism behind the conclusion, how to check it, and the cases where it does not hold. The next question a careful reader would ask gets a panel, a table row or a line in scope; a fact the reader could get wrong without it is not optional.
-- One sentence carries one fact; one panel answers one question. Say each fact once: when a table or diagram shows it, the text adds only what the figure cannot.
-- Call each thing by one name throughout the page, and use the name the reader already knows.
+- Each panel takes one question and each sentence makes one claim. A claim a table or diagram already shows is not restated; the text adds its reason or exception.
+- Keep one term per thing across the title, panels, diagram labels and table headers, and prefer the reader's own term.
- Give results with their evidence: a number with its unit, a file position, a source. When a value is unknown or estimated, say so in scope.
- Cite a `@source` for each claim the reader cannot check alone: protocol details, thresholds, benchmark figures, API behaviour. A rule of thumb without a source is labelled as one, or left out.
- Recompute every derived number before delivery and show the arithmetic once: “990 of 1000 requests at 80 ms → P99 = 80 ms; 11 slow → P99 = 600 ms.” Totals in tables add up.
-- Write steps as commands with the condition first: “If the build fails, read the log.”
+- Phrase an action as an imperative with its trigger in front: “If the migration reports a schema mismatch, roll it back before retrying.”
- When the reader must act or verify, end with a checklist panel: `- [ ] item`, one concrete check per item. Readers tick items on the page.
English: short sentences (under about 25 words), common words (use, before, to, because), active voice with a named actor.
@@ -258,7 +258,7 @@ After a pass, reply in two or three lines: the conclusion, then a Markdown link
Add `--repo-root <path>` when the draft uses `@code`. Finalize validates, atomically delivers and checks the HTML; it does not launch a browser, and its receipt records the browser gate as not run. A failure names the line, component, reason and a repair example; fix the draft and rerun to the same output path.
-Writing warnings apply the [Writing](#writing) rules: sentences over 50 Chinese units or 28 English words, paragraphs over four sentences or 120 units, chained “的”, light verbs, stock phrases and filler, unbounded quantities, “以上/以下/以内” after a number, long English words with a common equivalent, qualifiers such as “示例”, “未实测” or “illustrative” outside scope, a mostly bold conclusion and a scope over 50 units. Each warning names the matched text and a repair; fix it when the repair keeps the meaning. `--writing warn|strict|off` sets the severity.
+Writing warnings apply the [Writing](#writing) rules: sentences over 50 Chinese units or 28 English words, paragraphs over four sentences or 120 units, chained “的”, light verbs, set phrases, openers and sign-offs, unbounded quantities, “以上/以下/以内” after a number, long English words with a common equivalent, qualifiers such as “示例”, “未实测” or “illustrative” outside scope, a mostly bold conclusion and a scope over 50 units. Each warning names the matched text and a repair; fix it when the repair keeps the meaning. `--writing warn|strict|off` sets the severity.
## Panel replacement