Task: Write knowledge pages on structures and deal composition

Table of Contents

This page documents a task in the Documentation improvements story. It captures the goal, current status, acceptance, and any notes or results.

1. Goal

Add knowledge pages under doc/knowledge/ on trade structures and deal composition in ORE: how a deal is assembled from its parts, such as legs, components, and nested trades, and how ORE models the composed forms.

The pages complement the product catalogue in doc/knowledge/domain/. That catalogue describes products one by one. The new pages explain the structural patterns the products share. The exact set of pages is settled with the requester when the work starts.

2. Status

Field Value
State DONE
Parent story Documentation improvements
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-09-11

3. Acceptance

  • The knowledge pages on structures and deal composition exist under doc/knowledge/, link to and from the knowledge hub, and publish on the site.
  • compass lint --path doc passes and the site build succeeds.

4. Plan

Two knowledge pages, not one. The material splits on a natural seam: how a deal is composed, and what happens when the composed deal changes. Each page stands alone and links to the other.

  1. doc/knowledge/domain/trade_structures.org — the composition ladder, the rule that a leg is a trade with its own identifier, the deal topology, structure operations, and the linkages between trades.
  2. doc/knowledge/domain/confirmations_and_versioning.org — the confirmation model, the internal and external version rule, the amendment classification, and the confirmable events.

Grounding rules for both pages:

  • Use the market term, not a local one. Check each term against FpML, the ISDA Common Domain Model, the CFTC and EMIR rules, and the published vendor material for Murex, Calypso and OpenGamma Strata.
  • Cite the source for every external claim, with a link.
  • Tie each page to our implementation in an "In ORE Studio" section, and link the existing knowledge notes rather than restating them.
  • No pseudo-XML examples. Use tables and prose.

5. Notes

Both pages are domain-level. They ground development rather than describe a screen or a component.

6. Test Scenarios

Manual QA scenarios (scaffolded via compass add test_scenario, run through the QA Validation Runner panel) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

Scenario State Notes
     

7. PRs

PR Title
#2063 [doc] Add knowledge pages on trade structures and confirmations

8. Review

# Comment summary File Decision Notes
5637545488 Stray trailing ** on two headings, which renders as literal asterisks doc/knowledge/domain/confirmations_and_versioning.org Accepted Fixed in 9892d0922b. Removed the trailing ** from "The trade population" and "What travels with the trade".

9. Result

Two domain-level knowledge pages shipped under doc/knowledge/domain/, both wired into the knowledge hub and the tag inventory:

  • trade_structures.org — how a deal is built from its parts: the composition ladder, the rule that a leg is a trade with its own identifier, the deal topology, structure operations, and the linkages between trades.
  • confirmations_and_versioning.org — what a confirmation is, the internal and external version model, the four amendment axes, and the events that must be re-confirmed.

Every external claim cites a source: FpML, the ISDA Common Domain Model, CFTC Part 23 and Part 45, EMIR and its risk mitigation RTS, CPMI-IOSCO guidance on the unique transaction identifier, the ISDA Novation Protocol, EMTA NDF template terms, and OpenGamma Strata. The terminology is checked against the published vendor material for Murex and Calypso.

Acceptance is met: the pages exist, link to and from the hub, and the site build succeeds with both pages published. compass lint --path doc exits non-zero on dangling id links, and it does so identically on origin/main (620 violations on both), so this change adds none.

Emacs 29.3 (Org mode 9.6.15)