Plenty of tools will scan a codebase or platform and hand you a graph:
- dependencies
- services
- packages
- tables
- endpoints
- ownership tags
That can be genuinely useful for exploration and incident response. It is also, almost by definition, derived, lossy, and moving.
“The system” as one giant graph is often too big to reason about in a single session, for humans or for agents that need stable context windows.
So we get drift: several overlapping graphs, the actual runtime, the import graph, the org chart in microservice form, and the story people tell in chat.
But do you have an authoritative slice for “the work you're doing right now?”
RAG and “just retrieve the right files”?
Retrieval-augmented generation (RAG) and similar “chunk the repo, embed, fetch what looks relevant” setups can shorten searches and surface starting points, but they do not replace an agreed source of truth.
If the corpus is contradictory or stale, retrieval tends to return plausible fragments that still disagree on names, invariants, or “what we decided.”
The model then smooths those fragments into an answer that sounds aligned.
So RAG often shares the same failure mode as giant inferred graphs: high recall, weak guarantees.
What changes the game is small, curated context: a bounded packet tied to a unit of work, produced from declared structure (or at least reviewed and versioned), not from “whatever ranked well this afternoon.”
That’s the same intuition as a Topogram slice whether you paste it into a prompt, check it in CI, or ship it as JSON to an agent.
Why the slice matters more than the wallpaper graph
The unit of serious engineering is rarely “the entire architecture.” It’s a task, a journey, a widget, a bug, a requirement and its proof.
What teams need is not another poster-sized dependency map they scroll once and forget. We need a focused subgraph: just enough typed intent, constraints, and verification to:
- Agree on what “done” means.
- Implement or review without rereading the whole repo.
- Check changes against explicit references, not vibes.
That’s the importance of the slice: it is
- bounded
- portable
- aligned to the work item
It is small enough to be consistent and to stay consistent when the broader inferred graph shifts underneath you.
Authored intent + queryable slices (how Topogram thinks about it)
Topogram treats durable product and delivery intent as declarative records under topo/—a structured graph the CLI validates, not something you reverse-engineer after the fact and hope still matches Sunday’s deploy.
From that graph you can pull slices for the thing you’re doing: for example task-scoped or journey-scoped query output (topogram query slice ...) instead of asking a human or an agent to absorb the entire repository as “context.”
Example (proof repo): The brownfield proof program checks in a real exported task slice as an artifact—proof/artifacts/step-04-task-slice.json. (Also available at the bottom of this post.)
Developers and Agents inspect one task’s focused context as JSON, rather than spelunking the whole graph by hand.
For background on the structured graph idea (intent vs. stack realization, validation, contracts), see Topogram’s structured graph: concept and implementation.
For the SDLC slice of the same graph (pitches, requirements, tasks, proof), see the companion draft in this repo under dx/posts/topogram-sdlc-graph-devto.md until it is published.
Repository: github.com/attebury/topogram
{
"depends_on": {
"acceptance_refs": [
"ac_maintained_bulk_approve"
],
"affects": [
"cap_bulk_approve_submissions",
"cap_list_submissions"
],
"blocked_by": [],
"blocks": [],
"plans": [],
"satisfies": [
"req_maintained_bulk_approve"
],
"verification_refs": [
"verification_maintained_bulk_approve"
],
"verifications": [
"verification_adopt_brownfield_spec",
"verification_maintained_bulk_approve"
]
},
"focus": {
"id": "task_maintained_bulk_approve",
"kind": "task"
},
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
},
"related": {
"acceptance_refs": [
{
"description": "Given the brownfield app has an adopted Topogram spec, when bulk approval is added to the API, queue UI, widgets, and projections, then Topogram check, SDLC check, and app verification pass without generated source writes.",
"id": "ac_maintained_bulk_approve",
"kind": "acceptance_criterion",
"name": "Maintained Bulk Approve",
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
}
}
],
"affects": [
{
"actors": [
"actor_operator"
],
"creates": [],
"deletes": [],
"description": "Approves multiple selected content submissions.",
"id": "cap_bulk_approve_submissions",
"input": [
"shape_input_bulk_review"
],
"kind": "capability",
"name": "Bulk Approve Submissions",
"output": [
"shape_output_submission_card"
],
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
},
"reads": [
"entity_content_submission"
],
"reviewBoundary": {
"automation_class": "review_required",
"reasons": [
"writes_modeled_state"
]
},
"roles": [],
"updates": [
"entity_content_submission"
]
},
{
"actors": [
"actor_operator"
],
"creates": [],
"deletes": [],
"description": "Lists submitted content in review order.",
"id": "cap_list_submissions",
"input": [
"shape_input_list_submissions"
],
"kind": "capability",
"name": "List Submissions",
"output": [
"shape_output_submission_card"
],
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
},
"reads": [
"entity_content_submission"
],
"reviewBoundary": {
"automation_class": "safe",
"reasons": [
"read_only_surface"
]
},
"roles": [],
"updates": []
}
],
"blocked_by": [],
"plans": [],
"satisfies": [
{
"description": "The brownfield app must add bulk approval behavior from the adopted Topogram widget and API contract without regenerating the maintained source.",
"id": "req_maintained_bulk_approve",
"kind": "requirement",
"name": "Maintained Bulk Approve",
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
}
}
],
"verification_refs": [
{
"description": "Runs Topogram check, SDLC check, maintained app API behavior verification, and React build verification for the bulk approve checkpoint.",
"id": "verification_maintained_bulk_approve",
"kind": "verification",
"method": "runtime",
"name": "Maintained Bulk Approve Verification",
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
},
"scenarios": [
"brownfield_bulk_approve_api_ui_compile"
],
"validates": [
"cap_bulk_approve_submissions",
"cap_list_submissions"
]
}
]
},
"review_boundary": {
"automation_class": "review_required",
"reasons": [
"task_scope"
]
},
"summary": {
"claimed_by": [
"actor_operator"
],
"disposition": "active",
"domain": null,
"id": "task_maintained_bulk_approve",
"name": "Maintained Bulk Approve",
"priority": "medium",
"status": "in-progress",
"work_type": "implementation"
},
"type": "context_slice",
"verification": [
{
"description": "Runs Topogram check, SDLC check, agent brief, focused query packets, adoption receipts, and maintained app verification for the adopted brownfield spec checkpoint.",
"id": "verification_adopt_brownfield_spec",
"kind": "verification",
"method": "runtime",
"name": "Adopt Brownfield Spec Verification",
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
},
"scenarios": [
"brownfield_adoption_topogram_check_sdlc_check_app_verify"
],
"validates": [
"cap_approve_submission",
"cap_get_submission",
"cap_list_submissions",
"cap_request_changes",
"cap_submit_content"
]
},
{
"description": "Runs Topogram check, SDLC check, maintained app API behavior verification, and React build verification for the bulk approve checkpoint.",
"id": "verification_maintained_bulk_approve",
"kind": "verification",
"method": "runtime",
"name": "Maintained Bulk Approve Verification",
"ownership_boundary": {
"canonical_topogram": {
"agent_mode": "propose_review_adopt",
"owner": "human"
},
"generated_artifacts": {
"agent_mode": "regenerate_or_compare",
"owner": "engine"
},
"maintained_code": {
"agent_mode": "bounded_edit_only",
"owner": "human"
},
"proposal_surfaces": {
"agent_mode": "stage_map_customize_reject",
"owner": "human"
}
},
"scenarios": [
"brownfield_bulk_approve_api_ui_compile"
],
"validates": [
"cap_bulk_approve_submissions",
"cap_list_submissions"
]
}
],
"verification_targets": {
"generated_checks": [
"compile-check",
"runtime-check"
],
"maintained_app_checks": [],
"rationale": "Task slice points at verification covering the surfaces this task touches.",
"verification_ids": [
"verification_adopt_brownfield_spec",
"verification_maintained_bulk_approve"
]
},
"version": 1,
"write_scope": {
"generator_owned": [
"artifacts/**",
"apps/**"
],
"human_owned_review_required": [
"examples/maintained/proof-app/**"
],
"out_of_bounds": [
".git/**",
"node_modules/**"
],
"safe_to_edit": [
"topo/**",
"candidates/**"
]
}
}
Top comments (0)