parallax-house-view-diff

name

parallax-house-view-diff

description

Interface spec for verifying that a house view actually changes downstream portfolio output. Trigger: 'did the house view shift my portfolio output?' Describes the dual-leg paired-call protocol and output contract. NOT for loading or making a view (use /parallax-load-house-view or /parallax-make-house-view), not for comparing two saved views (use /parallax-make-house-view --compare). Calibration and reference runner are internal to Parallax.

House View Diff — Interface Spec

When not to use

• Just loading a view → use /parallax-load-house-view
• General portfolio building → use /parallax-portfolio-builder
• Comparing two saved house-view bundles side by side → use /parallax-make-house-view --compare

Gotchas

• This skill is a SPEC, not an executable runner. Consumers implementing the protocol provide their own execution + calibration.
• JIT-load _parallax/house-view/tests/portfolio_diff_harness.md for the protocol definition.
• Output MUST follow the <diff_output> JSON contract defined in the protocol spec.

Defines the protocol shape for verifying that an active house view shifts the output of a downstream consumer skill.

Purpose

A consuming agent running a portfolio workflow with an active house view should be able to demonstrate — in the same session — that the view actually changed the resulting portfolio vs. the baseline. This skill describes how that demonstration is structured. It does not ship the calibration thresholds or a reference runner.

Protocol (summary)

1. Leg A: execute the downstream skill with PARALLAX_HOUSE_VIEW_DIR pointing at an empty directory.
2. Leg B: execute the same skill with PARALLAX_HOUSE_VIEW_DIR pointing at the active view bundle.
3. Both legs must use identical build_stock_universe query parameters (except for tilt-prepended context).
4. Emit a <diff_output> JSON block comparing ranks and weights.
5. Append mechanical "what changed why" lines for shifted positions.

Full protocol: _parallax/house-view/tests/portfolio_diff_harness.md.

Cost: total cost is 2× the child skill's cost (Leg A + Leg B); see _parallax/token-costs.md.

Exit semantics

Consumer runners should surface at least three outcomes — PASS, WEAK, KILL — corresponding to the shift magnitude falling within the pass band, outside the warning band, or below the economic-viability threshold respectively. Specific band values are maintained internally by the reference-implementation provider.

Error Contracts

Consumers implementing the paired-call protocol must handle these failure modes:

Scenario	Behavior
Leg A succeeds, Leg B times out	Diff output shows baseline only. Surface message: "View load timed out; baseline results shown. Diff unavailable." Include Leg A results but do not emit PASS/WEAK/KILL verdict.
Leg A times out, Leg B succeeds	Diff output incomplete. Surface message: "Universe build timed out; view results shown. Diff incomplete." Include Leg B results but do not emit verdict.
Both Leg A and Leg B timeout simultaneously	No diff output possible. Fail loudly with explicit error: "Both legs timed out (>30s each). Diff protocol requires both results; cannot proceed. Retry with simpler theme or larger time budget." Do not emit partial output; do not emit verdict. Exit with error status.
Leg B fails (view validation error, not timeout)	If Leg A succeeded, surface both: Leg A results (solid) and error message for Leg B. Do not emit diff; do not emit verdict. Flag as "View validation failed — comparison incomplete."
Both legs fail (query error, bad theme)	Fail loudly with the error from whichever leg ran first. "Query error: [theme interpretation failed / no candidates found]. Could not construct baseline; diff not applicable." Exit with error status.

Troubleshooting

• "View did not load" → Check PARALLAX_HOUSE_VIEW_DIR resolution per _parallax/house-view/loader.md §1.
• "Paired-call protocol violated" → Ensure build_stock_universe query is identical across legs.
• "Markers absent" → Ensure output is wrapped in <diff_output> tags.