Retrieve Doc Workflow

Scope

• Query team domain knowledge: terminology definitions, enum values, status codes, business rules, system design, API descriptions, and configuration meanings.
• Query accumulated historical domain knowledge and business explanations.
• Search documents before explaining domain concepts to avoid guessing from generic semantics.

Not applicable for:

• Real-time online data such as orders, inventory, or voucher status. Use DB, audit, or log tools instead.
• Source-code search. Use a code agent or code retrieval tool instead.
• SOPs, troubleshooting steps, investigation processes, or tool invocation order. These are already encapsulated as team skills; use the corresponding skill.

Input

The caller should provide:

• query: A focused natural-language query containing key domain terms, error codes, enum names, API names, table names, or the original error message.
• component: The current team name. It may be empty; when empty, use the troubleshooting knowledge base.
• Optional kb_ids: Explicit knowledge-base overrides, used only for debugging or operations scenarios. They must not override a component whose KB access is denied.

Team Knowledge-Base Mapping

Use this table to decide whether KB retrieval is allowed for the component. When retrieval is allowed and explicit kb_ids are not provided, select the knowledge base by component:

Memory Usage Strategy

Whether to use Memory depends only on the Memory System field in the team mapping table above.

• disabled: Skip Memory KB and search the regular knowledge base directly.
• enabled: If the team has memory_project_ids, search Memory KB first with query and memory_project_ids, returning up to 5 results.
• When Memory KB has valid results, format and return them directly.
• When Memory KB returns successfully but has no results, return No relevant documents found for the given query. and do not continue to Smart KB.
• When the Memory KB call fails, returns an error, or the team lacks memory_project_ids, continue by falling back to the regular knowledge base.
• All current teams are disabled. In the future, only the value in the team table needs to change to enabled; the workflow remains the same.

Smart KB Usage Strategy

• Default --score-threshold 0.35.
• Sort results by score from high to low.
• Return at most --max-results 5 results.
• For table-type results, convert the first CSV data row into field: value format.

Executable Scripts

Scripts are responsible only for calling APIs and normalizing results. They do not choose teams, determine whether Memory is enabled, or decide fallback order.

Resolve script paths from the directory containing this SKILL.md. Do not assume the current working directory is the skill root; in installed environments execution may start from the parent .codex/skills directory. Do not hardcode machine-specific prefixes such as /Users/.../Desktop/code.

• Smart KB: "<retrieve-doc skill dir>/scripts/dod-query-kb" smart --query "<query>" --kb-id <kb_id> --max-results 5 --output json
• Memory KB: "<retrieve-doc skill dir>/scripts/dod-query-memory" search --query "<query>" --project-id <project_id> --max-results 5 --output json

How to interpret script output:

• ok=false: The API call failed or parameters were invalid. Check error.code and error.message.
• ok=true and data.total_returned == 0: The API returned normally but found no relevant results.
• ok=true and data.results is non-empty: Use source, content, and optional score from results.

Main Workflow

1. Get the current component.
2. Resolve the component in the team knowledge-base mapping.
3. If the component is mapped with access=denied, do not use explicit kb_ids, do not fall back to the default KB, and do not call Memory KB or Smart KB.
4. For a denied component, try to find another applicable team skill or domain skill that can answer the knowledge-point search goal without querying this KB; if no such skill applies, return Knowledge-base access is disabled for this component.
5. If the caller provides explicit kb_ids for an allowed component, use the explicit values first.
6. Otherwise, use the team knowledge-base mapping to select effective_kb_ids; for unknown teams, fall back to ["5297"].
7. Read the team's Memory System and memory_project_ids from the team mapping table.
8. If Memory System is enabled and memory_project_ids is non-empty, call:

"<retrieve-doc skill dir>/scripts/dod-query-memory" search --query "<query>" --project-id <project_id> --max-results 5 --output json

9. If the Memory KB command succeeds: return results when data.total_returned > 0; return No relevant documents found for the given query. when data.total_returned == 0; do not continue to Smart KB.
10. If the Memory KB command fails, Memory is not enabled, or memory_project_ids is missing, continue to the regular knowledge base.
11. Call Smart KB:

"<retrieve-doc skill dir>/scripts/dod-query-kb" smart --query "<query>" --kb-id <kb_id> --max-results 5 --output json

12. If Smart KB returns an error, retrieval failed; do not perform any other KB fallback.
13. If Smart KB returns normally but has no results, return No relevant documents found for the given query.
14. If there are results, return up to 5 document snippets in this format:

**Source:** <file name or source>
**Content:**
<relevant excerpt>

Query Strategy

• Prefer specific terms: error codes, enum names, API names, configuration keys, table names, Jira keys, service names, original error messages.
• Split broad questions into multiple focused queries.
• Do not search only for a single vague term such as oversold; add business context.
• If the first results are weak, retry with another kind of keyword: API, table name, status code, service name, error text, configuration key, or domain term.
• If the task requires SOPs, troubleshooting steps, or downstream tool invocation strategy, switch to the corresponding team skill; do not expect KB to return SOPs.

Output Requirements

• When citing retrieval results in the answer, keep the Source information.
• If only partial information is found, clearly state which parts were found and which parts are missing.
• If there are no results, retry with different keywords; if still no results, state that no relevant documents were found and do not fabricate.
• Do not treat retrieved snippets as real-time facts; real-time status must be verified with the corresponding real-time data tool.
• Do not treat retrieval results as SOPs; procedural actions should follow the team skill.