docs: expand guidance for setup and prompts

docs/ai/cross-platform.md

@@ -67,6 +67,21 @@ Debugging: Explain this error and list likely fixes in order.
 Understanding code: Summarize what this module does and call out risks.
 ```
 
+## Prompting Anti-Patterns (And Fixes)
+Common mistakes and better alternatives:
+
+Example prompts:
+```text
+Too broad: Fix everything in this project.
+Better: Refactor this file to remove duplication. Do not change behavior.
+
+Too vague: Make this code better.
+Better: Improve naming and add comments only where logic is complex.
+
+Missing inputs: Update the service to handle retries.
+Better: Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
+```
+
 ### Example: Too Broad vs Scoped
 Example prompts:
 ```text
@@ -86,6 +101,18 @@ Example prompt:
 Provide a 5-step plan to refactor this module. Wait for approval before edits.
 ```
 
+## Starter Prompts (Copy/Paste)
+Use these when you are not sure where to begin:
+
+Example prompts:
+```text
+Summarize this file in 5 bullets and list 2 risks.
+Refactor this function to remove duplication. Keep behavior the same.
+List tests I should add for this change.
+Explain this error and propose the top 3 fixes.
+Create a 5-step plan to split this class into smaller components.
+```
+
 ## Connecting Skills
 - Use skills for tasks with known workflows.
 - Combine multiple skills when a task spans domains.

docs/ai/overview.md

@@ -9,6 +9,14 @@ AI tools help with drafting, refactoring, explaining code, and accelerating rout
 3. Run a simple prompt to verify suggestions appear.
 4. Read the usage and token guidance to avoid accidental overuse.
 
+## Quick Setup Verification
+Use this checklist after install so you know things are working:
+1. Open a code file and type a short comment prompt.
+2. Confirm an inline suggestion appears within a few seconds.
+3. Open Copilot Chat and ask a short question.
+4. If nothing appears, restart the editor and try again.
+5. If still blocked, follow [Troubleshooting and FAQ](troubleshooting.md).
+
 ## What AI Is and Is Not
 - AI is a productivity assistant that can suggest code, summarize context, and propose solutions.
 - AI is not a source of truth. Always validate outputs with tests, code review, and domain checks.
@@ -51,6 +59,20 @@ Copilot is an AI coding assistant that integrates with editors and chats to help
 - Skills: Reusable knowledge or workflows the assistant can apply.
 - Tokens: The usage units that track AI consumption.
 
+## Where AI Assets Live (File Layout)
+Use this mental model so you know what is repo-scoped vs global:
+
+```text
+Repo (this guide)
+	docs/ai/               # Handbook content
+	assets/agents/         # Repo-shipped agent prompts
+	assets/instructions/   # Repo-shipped instructions
+
+User machine (global)
+	~/.agents/skills/      # Approved skills pulled by sync
+	~/.agents/agents/      # Optional global agents
+```
+
 ## Instructions (Repo Rules)
 Instructions are repo-scoped rule files that auto-apply based on file patterns. They set coding or documentation standards the assistant must follow when editing matching files.
 
@@ -74,6 +96,20 @@ Where they live:
 
 If you need the official agent assets repo, ask your team lead or check your internal setup docs.
 
+## How To Evaluate AI Output (Quick Rubric)
+Before you accept changes, check:
+- Correctness: Does it compile or pass tests?
+- Scope: Did it change only what you asked for?
+- Safety: No secrets, no policy violations, no risky changes.
+- Tests: Are new tests required or existing tests updated?
+- Review: Would you approve this in code review?
+
+### Example Review Prompt
+Example prompt:
+```text
+Review this change for correctness, scope creep, and missing tests. Keep the response under 8 bullets.
+```
+
 ## Key Repo Files (Why They Exist)
 These files explain how the AI docs are organized and how contributors should work. Each one has a different job.
 
@@ -137,6 +173,12 @@ Chat: What does this function do?
 Agent: Plan and refactor this module, then list tests to add.
 ```
 
+## Choosing The Right Chat Mode (Decision Tree)
+1. Do you only need an explanation or summary? Use Ask.
+2. Do you want a small edit in one file? Use Edit.
+3. Do you want steps before any edits? Use Plan.
+4. Do you want multi-step work across files or tools? Use Agent.
+
 ## First Prompt (Safe)
 Try a small, safe prompt to confirm everything is working:
 

docs/ai/troubleshooting.md

@@ -18,6 +18,14 @@
 4. Test with a small prompt in a new file.
 5. If still blocked, escalate.
 
+## Quick Setup Verification Checklist
+Use this after install or updates:
+1. Open a code file and type a short comment prompt.
+2. Confirm an inline suggestion appears.
+3. Open Copilot Chat and ask a short question.
+4. If nothing appears, restart the editor and try again.
+5. If still blocked, follow the escalation steps below.
+
 ## Extension or Plugin Conflicts
 - Disable overlapping AI extensions to avoid conflicts.
 - Restart the editor after enabling Copilot.