Agent Research Guide

Documentation spine · Getting started · Personas and journeys · Illustrated manual · Evaluation · Maintenance

This guide defines how an agent should use the UK Legislation OKF pack without loading the whole corpus or losing provenance.

Progressive discovery algorithm

1. Fetch https://chris-page-gov.github.io/okf-uk-legislation/okf-explorer.json.
2. Read the descriptor, overview, counts, notices and available facets.
3. Convert the user question into candidate title terms, citation terms, jurisdiction, time and document-type constraints.
4. Follow the descriptor's declared static-search manifest and filter postings; never guess a raw repository path.
5. Treat facet membership as snapshot-bound navigation metadata. In particular, the jurisdiction facet is territorial publication context inferred from official type code, not proof of provision-level extent or applicability.
6. Rank candidate works, but require identity confirmation from title/type/year/number/official ID.
7. Follow the declared relationship-adjacency manifest to load the selected work's bounded core assertion shard.
8. Resolve the selected route through the declared record locator. When the descriptor declares governed model_enrichment_v3, use that record-chunk index to load the same-index accepted enrichment chunk and retain only rows whose source or target is the selected route.
9. Load only the selected work's official CLML structure.
10. Locate the smallest relevant subdivisions and retain their source IDs.
11. Open selected-passage, work, contents and changes/effects links as required.
12. Check version, commencement, extent and amendment context.
13. Write discrete propositions with a citation ledger and explicit uncertainty.

The compact JSON record and relationship planes are suitable for AI access; they do not need to be duplicated into one giant RDF document. Root YAML-LD and JSON-LD, plus the Whole-Law federation's Turtle projection, describe the governed semantic contract; search postings, core adjacency shards and aligned accepted model-enrichment chunks provide scalable traversal.

Current limitation: core and model-assisted relationships have separate bounded paths. Core assertions use the relationship-adjacency manifest; governed v3 assertions use the selected route's record-locator chunk index and the aligned accepted enrichment chunk. Official effects remain available in the release-wide effect datapack and reconciliation material but are not yet source-and-target indexed per selected work. State that limit explicitly when answering a relationship-completeness question.

Source hierarchy

Prefer, in order:

1. official selected passage and official work/version pages;
2. official CLML/Atom/effects data;
3. normalized OKF identity and navigation metadata;
4. derived topic or quality metadata only as discovery context.

Never cite a derived topic as law. Never turn a catalogue absence into a claim that no legislation exists.

Minimum answer shape

{
  "question_id": "LQ001",
  "answer": "Answer-first synthesis with qualifications.",
  "propositions": [
    {
      "claim": "One material proposition.",
      "citations": [
        {
          "source_title": "Exact title",
          "url": "https://www.legislation.gov.uk/.../section/6",
          "passage": "Supporting passage",
          "version": "Current text checked on the stated date",
          "retrieved_at": "2026-07-11"
        }
      ]
    }
  ],
  "temporal_context": {
    "version": "...",
    "commencement": "...",
    "extent": "...",
    "amendments": "..."
  }
}

Guardrails

• Say when a conclusion depends on missing facts.
• Distinguish statutory wording from inference and application.
• Identify when case law, retained-EU interpretation or another source class is required.
• Do not describe the latest displayed text as operative everywhere without currency checks.
• Do not imply that the research bulk/SPARQL surfaces were harvested while anonymous access remains restricted.
• Treat source timestamp anomalies as source facts to flag, not values to silently repair.

Evaluation

Use the evaluation and quality guide and the 100-question suite. Automated scores validate observable evidence structure; expert review remains necessary for substantive legal correctness and forensic utility.