Github Issue Response

Responding on GitHub (amd/gaia)

Output style is not defined here. Follow ../../../CLAUDE.md → "How You Communicate": lead with the finding in plain words, layer file.py:line detail underneath, say each point once. This skill adds only the GitHub-specific protocol on top of that.

Automated PR-review policy — severity tiers, the nit cap, skip rules, length caps — lives in ../../../REVIEW.md. That file is the single source of truth for review scoring; don't restate or fork it.

🔒 Security — read this first

Never discuss vulnerability details in public. No exploit steps, no proof-of-concept, no technical analysis of how it could be abused.

Reported in a public issue: reply with a pointer to a private advisory, tag the maintainer, and stop.

Thank you for reporting this. This appears to be a security concern — please open a private security advisory instead: https://github.com/amd/gaia/security/advisories/new

Then tag @kovtcharov-amd.

Found during a PR review: open with 🔒 SECURITY CONCERN: <issue type>, tag @kovtcharov-amd, name the class of problem ("potential command injection") but not how to exploit it, and suggest the author take it to maintainers privately.

A 🔒 line and the maintainer tag always stay visible — never collapse them into a <details> block.

Escalate to @kovtcharov-amd

Security vulnerabilities · architecture and design decisions · roadmap or timeline questions · breaking changes and deprecations · external integration or partnership requests · AMD hardware specifics · anything you can't resolve from the docs.

Don't escalate: questions the docs already answer, simple usage questions, duplicates (just link the original), or feature requests that need community discussion first.

Before you reply

1. Search docs/ first — see docs/docs.json for the structure.
2. Check for duplicates — link the original instead of answering twice.
3. Cite real locations only. Reference file.py:line when you've actually found it; never guess a line number to look thorough.

Length caps by response type

Never: walls of unstructured text · repeating what the issue already says · generic advice that isn't GAIA-specific · opening with a code reference (Looking at src/gaia/foo.py:123, … reads like a diff review — the reader wants the finding before the line number).

Tone

Professional and friendly. Welcome first-time contributors and guide them gently; assume good intent even on unclear or duplicate issues; thank people for bug reports and ideas. External contributors won't know GAIA conventions yet — teach with a concrete example rather than correcting them abstractly.

Where things live (for pointing users at the right place)

Code:

• In-core agent framework: src/gaia/agents/ — base/, tools/, code_index/, registry.py
• Packaged agents: hub/agents/<id>/python/ — gaia (the flagship), chat (its base class), email, plus the hello-world / word-count / connectors-demo templates. Per-task capabilities (coding, data exploration, document briefs, …) are skills under hub/skills/.
• CLI: src/gaia/cli.py · MCP: src/gaia/mcp/ · LLM backends: src/gaia/llm/ (+ providers/)
• RAG: src/gaia/rag/ · Audio: src/gaia/audio/ · Eval: src/gaia/eval/ · API: src/gaia/api/
• Agent SDK: src/gaia/chat/ (AgentSDK) · Agent UI: src/gaia/ui/ (backend), src/gaia/apps/webui/ (frontend)
• Tool mixins: src/gaia/sd/mixin.py, src/gaia/vlm/mixin.py

Docs (external site: https://amd-gaia.ai):

• Getting started: docs/setup.mdx, docs/quickstart.mdx
• Guides: docs/guides/ — gaia, chat, agent-ui, email, talk, memory, starter-skills, composing-skills, terminal-hub, install, npu (list the directory; it changes)
• SDK reference: docs/sdk/ — core concepts, SDKs, infrastructure, mixins
• CLI: docs/reference/cli.mdx
• Troubleshooting: docs/sdk/troubleshooting.mdx · FAQ: docs/reference/faq.mdx
• Contributing: CONTRIBUTING.md · Dev setup: docs/reference/dev.mdx

For bugs, also check tests/ — a related test often reveals the issue or needs updating — and weigh security implications against docs/sdk/security.mdx.

Examples

✅ Bug report — diagnosis first, then two concrete asks:

Looks like RAG initialization didn't complete — that symptom is what happens when GAIA can't find a loaded embedding model. Two quick checks:

1. Did you run gaia init --profile chat first?
2. Can you share the output of gaia diagnostics?

If both look right, paste gaia chat --debug output and I'll dig in. Setup walkthrough: docs/guides/chat.mdx.

✅ Feature request — scope call first, then concrete building blocks:

Interesting idea. GAIA already ships Slack (gaia slack, docs/guides/slack.mdx); if this is about a different integration, you could build it from existing pieces: a connector under src/gaia/connectors/ for auth + API access, or a SKILL.md under hub/skills/ if it's a capability the flagship agent can drive with tools it already has (docs/guides/composing-skills.mdx). Running it on the local LLM backend keeps conversations private.

Interested in contributing it? CONTRIBUTING.md has the setup.

❌ Too generic — says nothing actionable:

This looks like a configuration issue. Try checking your configuration and making sure everything is set up correctly. Let me know if that helps!

❌ Too technical — leads with internals the reporter can't decode:

The error originates in src/gaia/rag/sdk.py:145 where RAGSDK.__init__ invokes _load_embedder, which raises if self.config.embedding_model can't be resolved by the Lemonade /api/v1/models endpoint…

Lead with "looks like RAG can't reach the Lemonade server", then drop the file references for whoever picks up the fix.

❌ Security — never post this, even though it's accurate:

The issue is on line 45 where you use subprocess.call() with user input. Here's how an attacker could exploit it: …

Escalate privately instead.