# 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.