story-data-analyze

story-data-analyze: a metric-system-driven novel data diagnostic workflow

Spawn version notice (does not block spawn): first read the project root .story-deployed of agents_version. When inconsistent with this version's agents_version: 39 (marker missing, field missing/non-integer, less than or greater than 39)check and spawn as usual based on file existence, and also report Notice: agents bundle 版本不匹配（项目 {N}，本版 39） and prompt to rerun /story-setup and then start a new session; when greater than 39, additionally prompt to first update oh-story-claudecode, and do not downgrade and overwrite with an old local setup. Only when agent files are missing, or the runtime does not expose custom agents, fall back to solo/direct, and report Fallback: ... -> solo. The specific placement of this Skill is still mapped according to the lane degradation matrix as degraded / solo; the current runtime defines malformed and missing registry as likewise treating the agent as unavailable.

Goal

This Skill is the sole entry point of the multi-Agent workflow, not a checklist of item-by-item numbers. It uses a machine-readable metric catalog, metric tree, and diagnostic routing as a shared semantic layer to complete the following closed loop; do not stop at a "numerical summary" or "insufficient sample":

数据可信 → 漏斗定位 → 异动定级 → 阅读对应文本 → 提出因果闭合的修改 → 发布后验证

The metric system is fixed into five categories, and they must not be flattened into unrelated single-point metrics:

1. Outcome metrics: whether the work continuously generates effective reading or effective bottoming-out; used to describe outcomes, not directly equivalent to an editable lever.
2. Driver metrics: how distribution, packaging reception, the golden first three chapters/segmented funnel, deep reading, and return visits jointly drive outcomes.
3. Diagnostic metrics: channel structure, chapter arrival, conditional follow-through, number of losses, rolling window entry/exit, etc., used to find where the problem occurs.
4. Guardrail/counter metrics: prevent breaking upstream promises, downstream follow-through, logical consistency, or traffic quality in order to improve one node.
5. Data quality metrics: refresh, completeness, formula consistency, version coverage, scope comparability, and contamination; when the quality gate fails, close business interpretation.

The layers of long-form works usually come from different windows or cohorts, and the entire tree cannot be falsified into a precise multiplication formula; for short stories, the same snapshot's impression→reading→15 seconds→30 seconds→60 seconds→bottoming-out can be strictly decomposed when the definitions are consistent.

Answer at least six questions each time:

1. Up to which day is the data counted, and has the refresh been completed?
2. How does the latest data change relative to the pre-modification baseline and the previous snapshot respectively?
3. Did the change occur in distribution, packaging, reading reception, return visits, or deep-chapter progression?
4. Which chapter, which paragraph, or which packaging element does the anomaly correspond to?
5. Why does the suggested modification have a logical chance to improve the target metric?
6. After publication, with what metrics and what window should it be verified, and which metrics must not worsen?

Separate "direction" from "strength of conclusion." Even with a small sample, report the absolute increment and the upward/downward direction truthfully, but do not disguise it as a causal conclusion.

Required resources

When processing Tomato data, read the following files by task:

• Each run: read references/workflow-contract.md, and comply with the Agent division of labor, the artifact state machine, the eight gates, and the fallback protocol.
• Each run: load dictionary/metrics.v1.json、dictionary/metric-tree.v1.json and dictionary/diagnostic-routes.v1.json; they are the machine authority for metric semantics, upstream/downstream relationships, and anomaly drill-down, respectively.
• To explain the metric system or troubleshoot metric linkages: read references/metric-system.md and references/diagnostic-routing.md。
• All Tomato tasks: read references/fanqie-metrics.md, and use only the chapters corresponding to long-form or short stories.
• To compare snapshots before and after, or determine anomalies: read references/anomaly-rules.md。
• To give revision suggestions or locate the main text: read references/text-drilldown.md。

When methods or cases need to be reused, first read 数据追踪/knowledge/index.json, then read 数据追踪/knowledge/methods/index.json or 数据追踪/knowledge/cases/index.json, and finally load only the matched entries. Knowledge entries are supporting evidence and cannot override the current official definitions or the facts of the current run.

When metric definitions are inconsistent with the current backend tooltip, the current official backend definition shall prevail, and the difference must be recorded in the report and reference files; do not guess definitions based on metric names.

Rules that must not be violated

1. Validate the data first, then interpret the business. Separate null values, non-refreshed data, lagging fields, rolling-window day changes, and genuine deterioration.
2. Long-form and short stories use different funnels. Do not use the long-form follow-through rate to explain the short-story bottom-out rate, and do not use the short-story click-through rate to replace long-form chapter retention.
3. Look at upstream first, but do not skip downstream facts because of it. No upstream volume lowers the credibility of downstream conclusions, but it does not mean that calculating the first three chapters or segmented retention can be skipped.
4. For percentages, first seek authoritative numerators/denominators. When the platform provides authoritative user counts or an explicit cohort base, report the absolute user count, conversion rate, percentage-point change, and sample size at the same time; when only percentages are shown, do not fabricate user counts. A "minimum compatible integer lower bound" may be calculated to check whether the curve has an integer explanation, but it must be marked minimum-compatible-lower-bound/display_only/non-authoritative/not-an-estimate: the true cohort may be any larger compatible solution; do not subtract across snapshots to obtain new user counts, and do not reuse a lagging follow field as the same denominator.
   • This lower boundis not a user count estimate, and must not enter sample thresholds, significance tests, confidence intervals, MDE, absolute loss, or "recoverable user count" calculations.
   • When no authoritative sample denominator with the same cohort and same definition as the current question can be found, you must register sample_size_qualified=false、sample_size=0、sample_size_authoritative=false、sample_aggregation=unavailable and a non-empty sample_unavailability_reasons; analysis uses sample_metric_id=UNAVAILABLE. Here, 0 is the status code for "qualified sample unavailable," not "the true number of readers is 0," and it is forbidden to substitute another count or compatible lower bound.
5. Channel readership is not equal to impressions. A bookstore/category value of 0 only means that reading UV for that channel was not observed; it does not mean zero platform impressions or failed recommendation evaluation.
6. Continue reading being 0 does not mean that absolutely no one returned across days. It only means that this entry did not record reading UV.
7. Currently reading user count is not historical cumulative user count. The Tomato long-form currently reading user count is the cumulative "listen + read" users over the most recent 14 days; it cannot be used to calculate chapter follow-through, and a single-day -1 cannot be directly called a loss of 1 person.
8. Low follow-through does not only require checking the end of the chapter. N→N+1 low explanation: readers who have read N did not enter N+1; check the entire chapter N, the end of the chapter, the next chapter title, and the beginning of the next chapter.
9. Cumulative snapshots are not a new-reader queue. Snapshot differences may be mixed with old readers continuing to advance; it can only be called "window incremental arrivals" unless the platform provides the same cohort.
10. It must not be guaranteed that revising the text will definitely increase the data. A reasonable causal chain between the modification and the metric must be demonstrated, and then verified by post-publication data.
11. The current workflow does not automatically modify the main text or publish. By default, deliver a specific modification plan and a data diagnostic card; currently there is only UNATTESTED_PROCEDURAL records, with no host signature; even if the user explicitly agrees in the session, it only forms an auditable handoff and cannot be automatically written or published by this run.
12. When search traffic is dominant, confirm self-visits. Before confirmation, retain the directional fact, but downgrade the text attribution; do not arbitrarily assume that all searches are from the author or acquaintances.
13. Must query along the tree; isolated spot checks are prohibited. Any anomaly must undergo the upstream, same-layer, downstream, and guardrail checks specified by the diagnostic routing; if the mandatory checks are not completed, text attribution must not proceed.
14. Agents must not exceed their authority and do it on behalf of others. The fetching Agent does not interpret business, the metrics Agent does not read the main text, the verification Agent does not polish the original conclusions, the text Agent does not modify the main text, and the watch Agent does not invent analysis.
15. Run artifacts must not masquerade as knowledge. Daily reports, raw data, one-off speculations, and unverified modifications cannot be directly placed into the knowledge base; promotion must pass through the supervision gate and retain the source hash.

Execution architecture and overall process

Run mode

• full: all five roles are available, and the complete workflow is executed.
• degraded: a certain lane is unavailable; execute according to the degradation matrix of the workflow contract and list the missing capabilities in the report.
• solo: when the runtime has no custom agents, the main Agent executes strictly in stages, but must not claim to have performed independent recalculation or supervision; the strength of conclusions is downgraded according to the missing gate.

Runtimes that support custom agents should preferentially use the following logical roles. First identify the current runtime and check only the corresponding directory: TRAE Code is .trae/agents/{agent}.md, Codex is .codex/agents/{agent}.toml; other runtimes can enter fullonly if equivalent definitions are deployed and sub-Agent tools are exposed. TRAE Code's .md must contain valid YAML frontmatter (name、description required,tools / disallowedTools as a comma-separated string), and select the subagent with the same name through the built-in Agent agent; do not pass Claude's subagent_type parameter as-is to TRAE. Codex uses the same-named agent_type. When the directory or registry corresponding to the current runtime is incomplete, enter references/workflow-contract.md according to the lane degradation matrix of degraded / solo, and must not pass off residual definitions from other endpoints on disk as registered Agents. The mere coexistence of .zcode/ in the project is not a basis for degrading the current runtime.

WorkBuddy uses a capped physical Agent pool and no longer registers all five logical roles as same-named physical cards. WorkBuddy physical registration only checks story-data-fetcher and story-data-readonly-runner: the former retains Bash fetching capability, and the latter has only Read, Glob, Grep, carrying the remaining four read-only logical roles. Project mode requires the .codebuddy/agents/ registry to actually list these two original names; plugin-only mode uses oh-story:story-data-fetcher and oh-story:story-data-readonly-runner, do not infer successful registration from the manifest or disk files.

The five logical roles are:

1. story-data-fetcher
2. story-data-metrics-analyst
3. story-data-method-validator
4. story-data-text-improvement-planner
5. story-data-supervisor

The main Agent is the sole orchestrator and final report writer. All sub-Agent prompts must be self-contained run_id, work identity, frozen inputs and hashes, deadline, change events, allowed outputs, and prohibited zones; sub-Agents must not recursively spawn. Each TRAE Code invocation must, within the built-in Agent , explicitly select the exact name from the table above and use the complete self-contained contract as the task body; if Agent the tool does not list that name, immediately degrade by lane, and do not pretend to complete an independent role recomputation through ordinary conversation.

WorkBuddy's story-data-fetcher still places the complete raw_capture contract directly into the physical fetcher's prompt. When invoking the remaining four logical roles, the main Agent must invoke the physical story-data-readonly-runner, and the prompt may only use the following wrapper:

{
  "logical_role": "<story-data-metrics-analyst|story-data-method-validator|story-data-text-improvement-planner|story-data-supervisor>",
  "logical_role_card_path": "<已解析的真实绝对路径>",
  "project_abs_path": "<当前作品项目真实绝对路径>",
  "task_contract": {"role": "<与 logical_role 相同>", "run_id": "<run_id>", "lane": "<该角色 lane>", "project_abs_path": "<与顶层字节一致>", "...": "<该逻辑角色的其余完整合同>"}
}

logical_role_card_path project mode can only resolve to <项目根>/.codebuddy/skills/story-data-analyze/references/workbuddy-role-cards/<logical_role>.md; plugin-only mode can only resolve to the CodeBuddy inline-replaced <CODEBUDDY_PLUGIN_ROOT>/skills/story-data-analyze/references/workbuddy-role-cards/<logical_role>.md. Before passing to the Runner, the real absolute path must be taken, confirming that the file exists, that its direct parent directory is the fixed role-card root for that mode, that the filename exactly corresponds to logical_role , and that it contains no unresolved placeholders. If the Runner or the corresponding role card is missing, the frontmatter is non-compliant, or the logical mapping is not unique, immediately degrade by that lane; do not switch to an old physical card with the same name, and do not pass off the existence of a disk card as registry availability.

Fixed state chain

INIT → RAW_CAPTURED → DATA_QUALIFIED → WINDOW_BOUND → METRICS_READY
→ ANALYZED → ANALYSIS_VERIFIED → TEXT_DIAGNOSED → SUPERVISED → REPORT_COMPLETE

Each step records immutable artifacts and hashes via scripts/data_workflow.py ; manually editing the analysis-runs manifest is prohibited. When the validator or supervisor returns it, create a new attempt from the earliest erroneous stage, up to three rounds, after which mark BLOCKED。

Three times isthe global RETURN cap shared by the entire run, not "three times per Agent" or "three times per root cause". The validator and supervisor combined accept at most 3 RETURNs; the 4th RETURN request directly marks the run as BLOCKED; root-cause counts are used only for diagnosis and cannot expand the total quota.

Fixed order: fetch → deterministic normalization and quality gate → metric analysis → independent method validation → text diagnosis → supervision → main Agent renders the daily report. The text Agent's input contract requires validator PASS, so it must not read the body in advance; at most it may preload in parallel public methods that do not contain the body, and these cannot be recorded as a valid text artifact.

The validator's "independent recomputation" is not restating the metrics artifact: for each fact it must reopen the frozen raw/normalized/window source, read the observation according to its JSON Pointer, and recompute according to the recorded calculation expression; PASS is allowed only when the fact selector, source refs, observations, formula, calculation, and result are all consistent and nothing is omitted.

Each Agent returns a unified envelope, and the workflow CLI records the role-specific lane payload. The main Agent must first perform deterministic adaptation: verify the envelope's run_id/role/status/input_hashes, then extract only the raw_capture/data_quality/analysis/validation/text_diagnosis/supervision object specified by the schema; it is prohibited to stuff the entire natural-language response or the entire envelope as-is into record --payload。

Phase 0: Determine the work type and analysis questions

First determine:

• Work type: novel / short story / both.
• User questions: routine daily report, revision effects, recommendation/distribution, first three chapters, a chapter breakpoint, packaging, full diagnosis.
• Target changes: what was changed, when it went live, and which metric it is expected to affect.
• Input mode: pull the latest backend / analyze a user-provided snapshot or screenshot / explain the method only.
• Work identity: lock the platform, work name, and work ID; when an account has multiple works, do not mix their numbers.

If analyzing long-form and short stories at the same time, build separate funnels and conclusions, and do not merge the samples.

Phase 1: Retrieve data and determine whether the data is usable

When the user requests the latest data or routine monitoring, execute the following for this project:

cd "<项目根>"
for PYBIN in python3 python py; do "$PYBIN" -c "" 2>/dev/null && break; done
"$PYBIN" "数据追踪/拉取番茄数据.py"

When the user explicitly specifies a local historical snapshot, uploads data, or only asks about the analysis method, do not pull new data without authorization; first verify the cutoff date and work ID of the given data.

Then complete five checks:

1. Login: when LOGIN_INVALID appears, stop and do not use old data to pass it off as the latest data; notify the user to log in again.
2. Date: confirm that raw's date is the run date anddata_until is the previous day; placeholder data captured before the platform updates at noon should be marked "platform has not yet updated".
3. Completeness: distinguish null, empty strings, missing fields, and real 0; the first three must not be automatically converted to 0.
4. Internal consistency: channel totals, readership counts, chapter arrivals, and the follow-through formula should be consistent within the allowed rounding error; when inconsistent, mark the specific fields and choose the more credible original headcount or wait for synchronization.
5. Definition basis: record cumulative/daily/7-day/14-day/custom period, whether there is cross-day duplication, and whether there is rolling deduplication.

If the sample denominator required by the current question cannot be authoritatively recomputed from the frozen source, do not substitute daily readership counts, 14-day reads, compatible integer lower bounds, or another eligible population. Continue generating facts and missing nodes coded as "sample unavailable"; in the end you may only give 样本不足/SAMPLE_INSUFFICIENT, but you may still truthfully report raw observations that do not depend on a fake denominator.

If raw's short_query.scope_verified_against_ui=false, the short story's yesterday_sum_*field may only be called "the original value of that snapshot interface"; only after opening the backend to verify the current period may it be called a cumulative or daily definition basis.

Output data quality labels:可分析 / 部分字段滞后 / 平台未更新 / 登录失效 / 口径未知. Only usable fields may enter subsequent judgment.

Phase 2: Establish the correspondence between changes and data windows

Read the change log in 数据追踪/番茄数据日志.md , and create an experiment card for each change:

Field	Required content
Change	Title/cover/description/specific chapters and paragraphs/update restoration, etc.
Launch time	Accurate to the minute, distinguishing save from actual publication
Target population	Readers actually exposed to the new version after launch
Primary metric	The one metric most directly affected by the change
Guardrail metric	Upstream or downstream metrics that should not decline because of the change
Pre-change baseline	Prefer 3–7 comparable complete data days, and retain at least the last pre-change snapshot
Minimum meaningful change	Write down the value and its source in advance: this work's history, business goals, or detectable effect; do not set it retroactively after seeing the results
First coverage window	The window in which real readers begin to see the new version after launch
First complete natural day	For more stable comparison, not equivalent to "first coverage"
Distractor	channel, hiatus/resumption, new chapter release, holidays, self-visits, simultaneous packaging changes, etc.

If the user confirms that all actual visits on a certain data date occurred after the change, that day can be regarded as having covered the new version; a complete natural day only improves comparability, and the preceding window cannot be mechanically judged as uncovered.

Mechanical date binding in the workflow uniformly uses Asia/Shanghai: first convert the timezone-aware published_at to Shanghai time;first_covered_data_date equals that local day, and only when it is published exactly at local 00:00:00 does first_full_data_date equal the same day, otherwise it is the next day. Then use the latest snapshot's data_until to uniquely derive three coverage states:

data_until < first_covered_data_date
  → NOT_COVERED
first_covered_data_date ≤ data_until < first_full_data_date
  → PARTIAL_DAY_COVERED
data_until ≥ first_full_data_date
  → FULL_DAY_COVERED

These three states describe "whether the statistical day may cover the version"; they do not prove that every visitor that day saw the new version; the online version still must be separately given version_evidence. No manually choosing the more favorable coverage state, and no writing partial-day coverage as full-day evidence.

Each time compare simultaneously:

1. the pre-change baseline;
2. the previous day or previous snapshot;
3. the latest snapshot;
4. when conditions permit, further compare the same day of week, same channel, and same recommendation stage.

Phase 3: Restore the complete funnel by work type

Long-form novel funnel

View in the following order, but retain the fact table at each layer:

1. Eligibility and distribution context: contract/recommendation validation stage, update continuity, violation notices, changes to title, cover, synopsis, or tags.
2. Reading sources: daily reading users, as well as the absolute UV and share of bookstore, category, bookshelf, continue reading, search, and other.
3. Packaging handoff: only calculate impression→reading when impression and reading data are available; when there is no exposure data, do not infer click-through rate from channel reading.
4. Golden first three chapters: first take the cumulative arrival rate R1/R2/R3/R4; only when an authoritative cohort base or API absolute user count exists, restore A1/A2/A3/A4。R4/A4 to judge whether Chapter 3 brings people into Chapter 4.
5. Deep chapter progression: check the maximum absolute churn count, the maximum conditional follow-reading decline, and the arrival count near the changed chapters.
6. Return visits and follow-reading: add to bookshelf, follow updates, urge updates, comments, ratings, and continue reading entry; strictly use their respective official definitions and appropriate eligibility denominators.
7. Recent activity: interpret the number of currently reading users using a 14-day rolling window, splitting new-entry days and roll-off days.

When authoritative user counts exist, calculate fixedly:

F1→2 = A2 / A1；L1→2 = A1 - A2
F2→3 = A3 / A2；L2→3 = A2 - A3
F3→4 = A4 / A3；L3→4 = A3 - A4

Only when the absolute user count source is authoritative and the version and definition are comparable, calculate the change-window increment ΔA1/ΔA2/ΔA3/ΔA4. When ΔA1 > 0 can report ΔA2/ΔA1, but it must be named "window incremental arrival ratio" and must not be called a strict new-reader follow-reading rate. If only the impression arrival rate is available, directly calculate R2/R1、R3/R2、R4/R3; the minimum compatible lower bound can only be used for single-snapshot consistency checks, and calculating Δ下界。

Short story funnel

View in the following order:

展示 → 阅读 → 15秒 → 30秒 → 60秒 → 触底 → 互动/转化

Fixed calculations:

点击率       = 阅读 / 展示
15秒留存     = 15秒人数 / 阅读人数
15→30承接率  = 30秒人数 / 15秒人数
30→60承接率  = 60秒人数 / 30秒人数
60秒后触底率 = 触底人数 / 60秒人数
整体触底率   = 触底人数 / 阅读人数

Also report the number of users lost in each segment, for example 阅读人数 - 15秒人数. Cumulative definitions and daily-summed definitions are kept separate; the same reader may be duplicated across days in interval data and cannot be directly compared with a full-period deduplicated cumulative count.

Phase 4: Identify anomalies and determine priority

Strictly follow references/anomaly-rules.md for execution, first classify the changes into:

1. Data anomalies: refresh lag, null values, formula inconsistency, statistical scope switching.
2. Traffic anomalies: changes in reads/impressions or channel structure.
3. Conversion anomalies: when the denominator is comparable, a change in conversion at some funnel step.
4. Rolling-window anomalies: changes in metrics such as the number of readers due to new days entering and old days rolling out.
5. Interaction anomalies: changes in the behavior of eligible populations such as adding to bookshelf, following updates, requesting updates, and commenting.

After identifying an anomaly, do not jump directly to the main text. For each hit node, execute the fixed route in dictionary/diagnostic-routes.v1.json :

1. first check the data quality gate and the metric's own denominator;
2. check upward for traffic scale, channel/packaging, and version events to determine whether it is merely upstream transmission;
3. check at the same level for synonymous or mutually validating metrics to rule out field lag and statistical scope changes;
4. check downward for absolute arrivals, conditional conversions, and guardrails to determine whether there is additional loss;
5. only when the remaining explanation still points to editable content, generate a specific text reading scope.

Each anomaly must save metric_id, current value, baseline, absolute change, relative change/percentage points, numerator and denominator, historical noise, MDE, sample status, results of required adjacent node checks, alternative explanations, and evidence level. If the directory does not provide a universal threshold, use the same-caliber historical baseline of this book; do not improvise a "platform passing line."

The baseline and current value of an anomaly must not be copied by hand.baseline_fact and current_fact must each use metric_id + 完整 dimensions to uniquely match one row in the frozen fact table;baseline/current must equal the selected fact value,delta = current - baseline，effect_size uses the same signed, unit-preserving difference,direction is mechanically derived from the difference. If a selector matches 0 rows or multiple rows, the fact is non-numeric, or the delta cannot be recomputed, the anomaly cannot pass the analysis gate.

Label key judgments with the nature of evidence: raw observation OBSERVED, recomputable derived DERIVED, association ASSOCIATION, hypothesis to be verified HYPOTHESIS; only randomized experiments or credible quasi-experiments may use CAUSAL。

Priority should not look only at the largest percentage point; consider in order:

• whether it is a data error;
• the affected absolute number of people when an authoritative denominator exists; when it does not, use arrival rate/percentage points and explicitly downgrade;
• whether it is upstream and how many subsequent readers it affects;
• whether it is aligned in location and time with recent changes;
• whether there is sufficient sample and a comparable baseline;
• fix cost and side effects.

Only when the number of people entering the node is the authoritative absolute number may the "recoverable number of people" be calculated as an auxiliary ranking:

可挽回人数 ≈ 该节点进入人数 ×（合理目标转化率 - 当前转化率）

The "reasonable target" should preferentially take the work's own stable history, the pre-change baseline of the same channel, or a pre-specified minimum meaningful change, and should not use an unverified universal platform passing line.

Write final status and direction separately:

• 样本不足；方向上行/下行/持平
• 改善/恶化（方向性，未达强结论）
• 改善/恶化（较强证据）
• 无明显变化
• 数据未覆盖改动
• 样本受自访污染

Conclusions must be bound item by item to changes, and must not give only a single status for the whole book.analysis.change_assessments[] must correspond one-to-one with window_bound.changes[] 's change_id one-to-one correspondence, while preserving coverage status, online version status, actually evaluated target metric, evidence, and rationale. Improvement/deterioration is not simply "value going up/down": it must be based on the metrics.v1.json of that metric in preferred_direction_by_metric interpretation; for example, a decrease in the number of churned users is improvement. Uncovered changes must use "data does not cover change + UNKNOWN"; when the sample is unqualified, a single ratio direction must not be used to upgrade a change to improvement or deterioration.

Do not force yourself to choose only one bottleneck. Output "primary constraint, secondary risk, items temporarily undeterminable"; prioritize resolving the valid anomaly that is most upstream and has the largest recoverable number of people.

Phase 5: Drill down from metric breakpoints to specific text

Only read the main text after completing funnel localization, but once a text revision suggestion is made, the text pointed to by the data must actually be read. Do not give empty talk such as "strengthen the hook, speed up the pace" based only on metrics.

Execution order:

1. Find the local file corresponding to the version already published on the platform; confirm whether the local draft and the online draft are consistent.
2. Read the promise before the breakpoint, the full text of the breakpoint chapter, and the title and opening of the next chapter; for short stories, read the actual paragraphs around 300/1000/2000 characters, and combine with natural scene boundaries.
3. Mark what readers already knew before leaving, what they expected, how much comprehension cost they paid, and why the next step was not worth continuing.
4. Find evidence from dimensions such as fulfillment of short promises, information increment, conflict escalation, protagonist agency, gains and costs, emotional intensity, logical continuity, genre fulfillment, poison points, and value rejection.
5. Cite specific chapters, paragraphs, or line numbers, and write clearly "text phenomenon → reader psychological mechanism → metric performance".
6. When multiple candidate causes coexist, sort them by evidence strength, first propose the minimal modification that can distinguish causes, and do not stuff all ideas into the main text at once.

For the specific mapping and checklist, see references/text-drilldown.md。

Phase 6: Write revision ideas as causal hypotheses

Each suggestion must use the following structure:

数据证据：哪个分子/分母在什么窗口异常
文本证据：具体章节/段落存在什么可观察问题
流失机制：该问题为什么会让这一节点的读者离开
修改动作：删/移/压缩/前置/补偿/升级/重写哪些内容
因果链：修改如何改变读者当下判断，从而影响哪个主指标
护栏：哪些上游承诺、人物逻辑、后续伏笔和指标不能受损
验证：何时、用什么基线和样本判断成功或失败

Before submitting a suggestion, perform a "logic closed-loop check":

• Is the modification position before the reader leaves?
• Does the modification directly address the identified mechanism, rather than repeating the original problem in a different wording?
• Does it fulfill the title/introduction/lead promise earlier?
• Does it add clear information, action, cost, or unresolved questions?
• Does it preserve character motivation, world rules, timeline, and subsequent foreshadowing?
• Might it improve the target metric while harming clicks, early retention, or long-term follow-reading?
• Does it change only one main variable, so attribution is possible after publication?

If a sub-Agent is available, the revision plan must undergo at least one structure/reader experience review; when settings or cross-chapter causality are involved, it must additionally undergo a consistency check. The purpose of review is to verify the causal chain and side effects, not to pursue rhetoric.

If a future run host provides HOST_ATTESTED authorization and permits the "this data analysis run" to execute modifications or publication, the execution command must also carry and exactly match the authorization artifact:

--analysis-run <run_id>
--analysis-proposal <proposal_id>
--analysis-action modify_text|modify_packaging|publish
--analysis-target <exact_target>
--analysis-target-sha256 <remote_payload_sha256，仅远端目标必需>

text_diagnosis.proposals[] The same proposal_id/action/target/target_sha256_beforemust first be registered. The hook will verify supervisor PASS, the complete hash chain, authorization status, and four-way consistency of proposal/action/target/hash; these are only additional conditions for a future trusted executor, not current execution permission. Ordinary daily updates do not carry these parameters and are not affected by the data analysis gate.

At the current runtime, only attestation_status=UNATTESTED_PROCEDURAL: It binds the user message hash, event ID, run, chain head, proposal, action, target, and pre-change hash into an auditable record, but there is no unforgeable user event signature provided by the host. The auto-execution gate requires HOST_ATTESTED, and the current runtime cannot generate this state. Therefore, even if APPROVED procedural record has been written, itis prohibited for this workflow to automatically modify the main text, modify the packaging, or publish; the plan can only be handed to the user for manual execution, or re-authorized by a trusted executor that can provide a host signature in the future. Neither command parameters nor hook hits can elevate UNATTESTED_PROCEDURAL into executable authorization.

Phase 7: Post-publication verification

Pre-publication record: original location, modification summary, publication time, primary metric, guardrail metric, expected direction, minimum meaningful change, and confounders.

Post-publication:

1. First confirm that the data window actually covers the new version; when there are no new qualified samples, write "no new samples" rather than "modification ineffective."
2. Check the early direction daily, but use the approximately one-week observation period recommended by Tomato official as the main review window; when the first day is affected by word count and refresh, mark it separately.
3. Compare the pre-change baseline, the previous snapshot, and the latest snapshot at the same time, and check whether the channel composition has changed.
4. When the primary metric rises but the guardrail drops significantly, do not judge it a success; identify the side effect and decide whether to roll back or make a second small change.
5. When multiple changes overlap, the traffic stage changes, or self-visit contamination occurs, lower the strength of attribution.
6. Append the reconciled data, authoritative absolute headcount (if any), display rate, modification time, basis for judgment, and next verification date to the data log; the minimum compatible lower bound must be listed separately and must not be subtracted across days. Do not tamper with historical conclusions; when correction is needed, append an erratum.

Samples and conclusion strength

The following are internal analysis guidelines, not official Tomato thresholds:

• Effective samples < 30: For the status, write "insufficient samples"; still report the raw observations, the display rate direction, and any existing authoritative absolute change, do not treat the compatible lower bound as samples or headcount, and do not make causal attributions.
• Effective samples 30–99: Give only directional conclusions; require absolute headcount and rate to move in the same direction, at least two same-direction movements in comparable windows, or the aggregate window to exceed its own baseline noise.
• Effective samples ≥ 100: Only when combined with confidence intervals, the preset minimum meaningful change, and guardrail metrics may a stronger conclusion be given.

"Effective samples" here refers only to sample_size_qualified=true and a denominator for which all sample evidence is authoritative and recomputable from a frozen source. When samples are unavailable, follow sample_size=0 + sample_metric_id=UNAVAILABLE into "insufficient samples"; this status encoding must not be interpreted as an actual zero readers.

Sample size is not the only condition. Even if the headcount is sufficient, as long as the channel, version, statistical scope, or recommendation stage is not comparable, it must also be downgraded.

Output format

First give a one-sentence conclusion that does not evade the direction, then give the evidence:

# 一句话结论
数据截至 YYYY-MM-DD；[改动]当前状态为[状态]，方向[上行/下行/持平]；主要瓶颈在[漏斗节点]。

## 1. 数据质量与覆盖
- 更新时间/截止日：
- 可用与滞后字段：
- 改动覆盖窗口：
- 样本与污染风险：
- 指标目录/方法/运行 ID：

## 2. 漏斗对比
| 节点 | 修改前基线 | 前一快照 | 最新 | 绝对变化 | 转化变化 | 状态 |

## 3. 异动与问题定位
- 最大有效异动：
- 受影响绝对人数（仅权威来源；否则写不可得）：
- 首要约束 / 次要风险 / 暂不可判定项：
- 已完成的上游/同层/下游/护栏联查：
- 排除的替代解释：

## 4. 文本下钻证据
- 位置：第N章第X段 / 第X–Y字
- 原文现象：
- 读者心理与流失机制：

## 5. 修改实验卡
- 具体修改：
- 逻辑因果链：
- 主指标：
- 护栏指标：
- 最小有意义变化及来源：
- 风险与一致性检查：

## 6. 验证计划
- 首个覆盖窗口：
- 主要复盘窗口：
- 成功/失败判据：
- 下一步：

## 7. 工作流验收
- Requested / Effective Mode：
- Validator：PASS / REWORK / NOT_RUN
- Supervisor：PASS / RETURN / BLOCKED / NOT_RUN
- 证据强度上限与未过门禁：

The daily report may be compressed, but it must retain: data cutoff date, whether the data is normal, current direction, absolute increment, the funnel by first three chapters or short-story segments, bottleneck location, specific modification/observation actions, and next verification time.

Knowledge maintenance

The knowledge layer maintains only two types of content:

• methods/: metric definitions, calculation methods, anomaly detection, attribution boundaries, text mapping, and experimentation and review methods; when updating, record the source, scope of applicability, version, and counterexamples.
• cases/: Analytical cases that have passed a complete gate review; they must preserve data context, metric version, anomalies and cross-checks, textual evidence, revision hypotheses, alternative explanations, result status, and applicable boundaries.

Cases are marked separately as "analysis quality verified" and "change effect verified". Without data from a qualified post-release window, it can only be outcome_unverified; high-quality cases with no effect, regression, and inconclusiveness are equally worth retaining, and one must not accumulate only success stories. Any promotion goes through the workflow CLI's promote-case or promote-method, and is endorsed by REPORT_COMPLETE + validator PASS + supervisor PASS + 完整 hash 链 ; method revisions must create a new version and declare supersedes, and must not overwrite the old version.

verified_improvement / verified_regression / verified_no_effect must also be supported by at least twodifferent frozen latest snapshot windowsof complete validation runs; runs with different run IDs but the same latest_snapshot.source_sha256 + data_until still count as the same window, and duplicating the same snapshot to manufacture a "reproduction" is prohibited. Each validation run must also have complete day coverage, a verified online version, no fewer than 100 authoritative qualified samples, validator/supervisor pass, and consistency with the same change_id and result direction.

Promotion uses transactional writes: the promotion artifact embeds the knowledge document to be promoted and enters the hash chain, then the knowledge file is created. Uncommitted *.attempt-*.json left by a crash, or a committed but missing knowledge file, can only be recovered by running scripts/data_workflow.py recover --run-id <run_id> ; recover moves orphan attempts into that run's recovery/<timestamp>/ quarantine directory (without deleting them), and rebuilds missing knowledge only from committed, hash-matching embedded documents. recover does not infer business facts, does not advance status, and cannot repair artifacts without a valid evidence chain.

It is prohibited to output

• "recommendations are 0, so the main text must be fine."
• "continue reading is 0, so nobody came back across days."
• "add to bookshelf is 0, so the algorithm simply gives no traffic."
• "chapter N's completion rate is low, so chapter N is bad."
• "the follow-read rate is low, just change the last sentence into a cliffhanger."
• "the ratio dropped, so the work has deteriorated."
• "the sample is insufficient, so nothing can be seen."
• "after the change it will definitely rise."

Rewrite these sentences into conclusions with a defined scope, absolute headcounts, direction, uncertainty, and verifiable actions.