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