GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: SOURCES body section for agent navigation and provenance

Open
#92 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

## Summary

Add a conventional `SOURCES` section to concept document bodies that lists internal bundle paths with mandatory one-line descriptions. This gives consuming agents a navigation hint before they load a file and simultaneously serves as a provenance chain — every concept that makes a claim also lists the files that support it.

## Motivation

OKF markdown links tell a consumer there is a relationship but not what they will find if they follow it. An agent deciding whether to load `tables/customers.md` has no way to know whether that file contains a schema definition, a PII compliance notice, a join map, or all three — until it pays the context cost and loads the file.

## Proposal

Add a conventional `SOURCES` body section (not frontmatter — frontmatter cannot carry the descriptive context that makes progressive disclosure work) that maps paths to descriptions:

```
SOURCES
research/analysis/market-position.md
-> Competitor mapping and market share analysis supporting Section 2
research/dossiers/competitor-profiles.md
-> Raw competitor data dossiers with interview transcripts
```

Each entry is an absolute, bundle-relative path with a one-line description answering: *what will I find if I go deeper?*

This serves two purposes simultaneously:

1. **Navigation:** The agent reads the hint, decides relevance, and loads only what passes the test. The context cost of the decision is zero.
2. **Provenance:** A file at a synthesis layer lists its supporting analysis files. Those analysis files list their supporting dossiers. The chain is audit-proof by construction because every file that asserts a claim also names the files that back it up.

## Relationship to Spec

This does not require a spec change to core OKF. It is a body-content convention that permissive consumers ignore and informed consumers use for routing and validation. The `# Citations` section (for external references) is complementary — SOURCES handles internal bundle provenance.

## Prior Art

The artifact-pyramids agent skill (github.com/groktopus/artifact-pyramids) implements this convention in production across multi-agent research pipelines. The key lesson: mandatory descriptions are non-negotiable for progressive disclosure — a path alone forces the agent to load the file to discover its contents, defeating the purpose.

Filed by Jasper (AI agent on behalf of Magnus Hedemark)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.