gdref-agent-retrieval-workflow

name	gdref-agent-retrieval-workflow
description	Operational workflow for deterministic, low-token retrieval of Godot skills and documentation using the gdref index tool.
tier	operational
godot_version	4.6+
doc_anchors	["godot-docs/tutorials/editor/command_line_tutorial.rst","godot-docs/about/docs_changelog.rst"]
tags	["workflow","retrieval","tooling"]
depends_on	["godot-skills/godot-operational/documentation-version-governance-workflow/SKILL.md","godot-skills/godot-operational/developer-skills-reflection-router/SKILL.md"]

GDRef Agent Retrieval Workflow

Use When

• Agents need reliable skill/doc retrieval without broad keyword scanning.
• Context token budgets are tight and path-only answers are preferred.
• Symbol-level lookup is needed for class/method APIs.

Outcomes

• Retrieval is index-based and deterministic.
• Skill/doc lookup returns direct paths with low output noise.
• Cross-reference from docs to skills is fast and consistent.

Required Rules

• Build/refresh gdref index before major retrieval sessions.
• Prefer bridge and doc class/method commands over text searches.
• Use --agent output mode for compact machine-readable responses.
• Keep lexicon concept map updated when new Godot skills are added.

Workflow

1. Run ./gdref index build then ./gdref validate.
2. Resolve symbols with doc class / doc method for exact API targets.
3. Resolve coverage with bridge class / bridge doc / bridge skill.
4. Use find for concept retrieval when exact symbol is unknown.
5. Feed returned paths directly into downstream agent reasoning.

Validation

• doc class EditorUndoRedoManager resolves a single class file path.
• bridge class EditorUndoRedoManager returns relevant skill paths.
• --agent find "multiplayer intent replication" returns compact JSON with non-empty skills and docs.

Failure Modes

• Index is stale and returns missing/outdated paths.
• Keyword-only retrieval bypasses bridge resolution and increases false matches.
• Lexicon is not maintained as skills evolve, reducing recall.

Local Doc Anchors

• godot-docs/tutorials/editor/command_line_tutorial.rst
• godot-docs/about/docs_changelog.rst