| 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)
- Leg A: execute the downstream skill with
PARALLAX_HOUSE_VIEW_DIR pointing at an empty directory.
- Leg B: execute the same skill with
PARALLAX_HOUSE_VIEW_DIR pointing at the active view bundle.
- Both legs must use identical
build_stock_universe query parameters (except for tilt-prepended context).
- Emit a
<diff_output> JSON block comparing ranks and weights.
- 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.
