Document-as-Code Lab

Chapter 9 · in-review

Information You Can Explore

In reviewChapter informationUpdated

Recent changes

  1. Refine tutorial narrative and adopt v1.3 editorial guidanceAnders Gustafsson · · 9b63bdb
  2. Implement tutorial v1.2 agent knowledge and scenario checksAnders Gustafsson · · 6d8ee1d
  3. Remove quality-checks chapter and update tutorial navigationAnders Gustafsson · · ba303dd

Status comes from chapter metadata; history reflects the source revision used for this build.

A contract manager receives a proposed amendment. Which deliveries deserve review before the team accepts it? The answer depends on connections between agreements, projects, and deliveries, not just the wording of one document.

The onboarding examples showed how to identify, connect, and process information. Here we use a different fictional setting to explore what happens when readers choose the question and follow the relationships themselves.

A customer, two projects, several commitments

Our customer has two projects. A framework agreement covers both, while a delivery order covers one. Proposed amendment AMD-001 would change terms for its interface package, DEL-101. The acceptance workshop, DEL-102, depends on that package.

These are fictional teaching records, maintained as Markdown sources in the repository, not actual contracts. Their relationships are recorded explicitly rather than guessed from titles.

Same information, different questions

Consider three questions from three different people.

Account manager: Which projects share an agreement?

Show the customer, its projects, and the agreements linked to each one. The shared framework agreement becomes visible without opening every contract.

Delivery manager: What depends on the interface package?

Switch to a delivery-focused view. DEL-102 depends on DEL-101. A list of documents would be less useful than seeing that relationship directly.

Contract manager: What should we review if the amendment is accepted?

Follow AMD-001’s connections to the affected delivery, its project, and dependent work. The links identify possible review work; the proposal is not yet effective.

The underlying records have not changed. Only the question and the view have changed.

Explore: One source, three views

The website’s Contract Explorer reads the same nine records for all three views. It is a fictional example, updated when the site is built. In GitHub’s Markdown preview, use the record table and linked sources to follow the same relationships.

The explorer offers three selectable perspectives:

ViewReader can doWhat it reveals
RelationshipsSelect a customer, project, agreement, or deliveryConnected records, with labeled links
CommitmentsFilter deliveries by project or agreementDelivery names, planned dates if recorded, and associated terms
Change impactSelect an agreement or proposed amendmentDirect links and possible downstream review candidates

Selecting a record reveals its source file, status, revision, and explicit relationships. The interface distinguishes recorded connections from possible impacts inferred by following those connections.

AMD-001 remains proposed, not effective. Its lifecycle status does not establish whether a delivery is complete; the explorer shows delivery execution status separately.

The explorer is not a new system of record. Selection and filtering change the view, not the maintained files. Source edits appear after the site is rebuilt.

If proposed amendment AMD-001 were accepted, which deliveries deserve review? Start with Explore change impact below, then inspect the directly linked delivery and follow the dependency to a further review candidate. Without JavaScript, read the Change impact list and linked records; the same recorded paths remain available.

The direct links identify DEL-101. Because DEL-102 depends on it, DEL-102 is a further review candidate. Neither connection decides what the team should change. You can inspect the same chain in the sources below.

Inspect the example records

RecordWhat it representsConnection
CUST-01Northstar LogisticsCustomer for both projects
PRJ-101Depot rolloutIncludes DEL-101 and DEL-102
PRJ-102Training servicesIncludes DEL-103
AGR-001Framework agreementApplies to both projects
AGR-002Project delivery orderApplies to PRJ-101
AMD-001Proposed amendmentProposes changes to AGR-002 affecting DEL-101
DEL-101Interface packagePart of PRJ-101
DEL-102Acceptance workshopPart of PRJ-101; depends on DEL-101
DEL-103Training packagePart of PRJ-102

Why this is more than a dashboard

A dashboard usually answers a set of predefined questions. An exploratory interface allows readers to select an object, follow a relationship, and ask the next question.

That is where structured information becomes especially useful. A record has an identity; its relationships have meanings; its status belongs to a defined process. Those details let people navigate the information rather than only read a published snapshot.

The same approach can support a knowledge graph, portfolio overview, dependency view, or AI-assisted query interface. Each is an application of maintained information—not a reason to maintain separate copies of it.

Keep the connection to the sources

An attractive visualization can still mislead. A line between two objects must mean something specific. A date needs a source. A missing link means no recorded link, not proof that the objects are unrelated.

When a source changes, generated views should refresh through a defined process. Users should be able to inspect which source and revision produced the view. If a proposed change may affect other items, treat them as review candidates, not automatically approved updates.

Explore further: Want to create reusable diagrams and views? The visual-source guide explains Mermaid, SVG, raster images, source provenance, and accessible alternatives. Reading needs no setup; optional rendering examples identify their tools.

A useful explorer lets you move from a question to recorded evidence without maintaining another copy of the information. Those views still need to be rebuilt when sources change. Chapter 10 follows how this tutorial automates that work.

Contract Explorer

Fictional example · Updated at build time

Snapshot built · 9 maintained records

Recorded links for CUST-01 · Northstar Logistics

Recorded links · Table alternative to the graph
FromRelationshipTo
CUST-01 · Northstar LogisticsownsPRJ-101 · Depot rollout
CUST-01 · Northstar LogisticsownsPRJ-102 · Training services

Agreement coverage is traced through each delivery's recorded project. Agreement lifecycle does not determine delivery execution status. Dates below are plans, not completion evidence.

Delivery commitments
Delivery / ProjectPlanned dateExecution statusAgreements / Recorded terms
DEL-101 · Interface package
PRJ-101
2026-11-10planned

AGR-001 · effective
Shared terms: delivery scope and acceptance evidence are defined by the associated project order. This fictional agreement applies to both projects; it does not record whether any delivery is complete.

AGR-002 · effective
Current terms: provide the interface package for review before the acceptance workshop. Acceptance requires a recorded customer decision. No actual acceptance decision is recorded in this dataset.

DEL-102 · Acceptance workshop
PRJ-101
2026-11-17not-recorded

AGR-001 · effective
Shared terms: delivery scope and acceptance evidence are defined by the associated project order. This fictional agreement applies to both projects; it does not record whether any delivery is complete.

AGR-002 · effective
Current terms: provide the interface package for review before the acceptance workshop. Acceptance requires a recorded customer decision. No actual acceptance decision is recorded in this dataset.

DEL-103 · Training package
PRJ-102
Not recordedplanned

AGR-001 · effective
Shared terms: delivery scope and acceptance evidence are defined by the associated project order. This fictional agreement applies to both projects; it does not record whether any delivery is complete.

AMD-001 lifecycle status: proposed. Following links identifies possible review work, not accepted updates.

Directly recorded links

  • AMD-001 amends AGR-002 (recorded)
  • AMD-001 affects DEL-101 (recorded)

Traversal-derived review candidates

  • Review candidate: PRJ-101
    • AMD-001 affects DEL-101 (recorded)
    • DEL-101 belongs to PRJ-101 (recorded)
  • Review candidate: DEL-102
    • AMD-001 affects DEL-101 (recorded)
    • DEL-102 depends on DEL-101 (recorded)

Selected record

CUST-01 · Northstar Logistics

customer · Record status: active

Northstar Logistics is the fictional customer for the depot rollout and training services projects.

Revision: 472cdea9384ef7b7e4065a27159982a28b216b00
SHA-256: 9b0877c9e46e51fdd5ba40707202ea752fca4afd4a5224c3f8e5a7de247f7865

Read maintained Markdown: examples/contract-explorer/records/CUST-01.md
All maintained records and relationships

AGR-001 · Framework agreement

agreement · Agreement lifecycle status: effective

Shared terms: delivery scope and acceptance evidence are defined by the associated project order. This fictional agreement applies to both projects; it does not record whether any delivery is complete.

Revision: 472cdea9384ef7b7e4065a27159982a28b216b00

SHA-256: 5865b408ede4c0f0cf6df2b4a097f9a5cc1b2959ea12b7ced25c053e869fc289

Read maintained Markdown: examples/contract-explorer/records/AGR-001.md

AGR-002 · Project delivery order

agreement · Agreement lifecycle status: effective

Current terms: provide the interface package for review before the acceptance workshop. Acceptance requires a recorded customer decision. No actual acceptance decision is recorded in this dataset.

Revision: 472cdea9384ef7b7e4065a27159982a28b216b00

SHA-256: 1777f3eea08352b3f98915340d46c7629e2aeaea7b4a40859ef8d137f58d2b18

Read maintained Markdown: examples/contract-explorer/records/AGR-002.md

AMD-001 · Proposed acceptance amendment

amendment · Amendment lifecycle status: proposed

Proposed terms: require a written interface test summary before the customer acceptance decision for DEL-101. This proposal is not effective and does not replace the current delivery order.

Revision: 472cdea9384ef7b7e4065a27159982a28b216b00

SHA-256: 9b36563c8ff95dd7da0daf04f33a885cc42b25503afb30a77e80669af34de8f5

Read maintained Markdown: examples/contract-explorer/records/AMD-001.md

DEL-102 · Acceptance workshop

delivery · Delivery execution status: not-recorded

Review the interface package with the customer. No delivery execution state is recorded. The dependency identifies the input needed for the workshop, not proof of a delay.

Planned date: 2026-11-17

Revision: 472cdea9384ef7b7e4065a27159982a28b216b00

SHA-256: 52d6c0e3f2fbcd2e139a0ae6e797f009e4777af2282a7999cb614b12eb996145

Read maintained Markdown: examples/contract-explorer/records/DEL-102.md

PRJ-101 · Depot rollout

project · Record status: active

Deliver the interface package and acceptance workshop. Agreements and deliveries record their own links to this project.

Revision: 472cdea9384ef7b7e4065a27159982a28b216b00

SHA-256: 06c81f9d1ecd5ae16f8c226211773045b07d6100bda9756443508b057e560073

    Read maintained Markdown: examples/contract-explorer/records/PRJ-101.md

    PRJ-102 · Training services

    project · Record status: active

    Prepare a training package for the customer. The shared framework agreement also applies to this project.

    Revision: 472cdea9384ef7b7e4065a27159982a28b216b00

    SHA-256: bdfe153d39c590de986d25bdaddcd4a8563c2648c78d6e3e4b192deb05ece585

      Read maintained Markdown: examples/contract-explorer/records/PRJ-102.md

      Check your understanding

      1. What changes when you switch from a customer-focused view to a delivery-focused view of the same maintained records?
      2. AMD-001 is proposed and linked to DEL-101. DEL-102 depends on DEL-101. What does following these connections establish?