claw/docs/superpowers/references/tq-lineloss-lessons-learned.md

tq-lineloss Report Lessons Learned

These lessons capture the non-negotiable rules that the generated scene skill platform must preserve when turning the current tq-lineloss-report scenario into future staged browser-script skills.

Routing

• Deterministic intranet routing must require the exact 。。。 suffix.
• Unsupported scenes must fail closed with a prompt instead of falling back to hidden page defaults or legacy one-off logic.
• Ambiguous scene matches must fail closed and ask the operator to clarify.

Canonical parameters

• Organization resolution must come from an explicit dictionary entity resolver.
• Period resolution must require an explicit month or week expression from the operator instruction.
• Generated browser scripts must receive canonical arguments and must not re-parse raw natural language.
• Page defaults are not allowed to silently fill missing organization or period values.

Bootstrap

• Every generated browser-script scene must declare expected_domain and target_url in scene.toml.
• The runtime owns target URL/domain validation and bootstrap; generated skills should not hard-code Rust-side bootstrap behavior.
• When page context is present, routing can use it for scoring, but the manifest remains the registration contract.

Artifact contract

• Report collection skills must return a generic report-artifact payload.
• Exportable artifacts must include stable columns, human-readable column_defs, and row data.
• When postprocess.exporter = "xlsx_report", Rust should perform the XLSX export generically from the artifact fields.

Validation

• A generated scene is not complete until deterministic routing, registry loading, browser-script execution, and postprocess tests cover it.
• Pipe and browser-ws service paths must stay covered because both remain supported runtime entrypoints.
• Manual service-console smoke testing must verify the real callback-host bootstrap path.
• Timeout diagnostics must preserve enough callback-host stage information to identify whether failure happened before helper load, before helper ready, or during command execution.