From b87fcab24878c483f62c4652ed09a0da9c319ffa Mon Sep 17 00:00:00 2001 From: Matt Bruce Date: Tue, 10 Feb 2026 15:30:04 -0600 Subject: [PATCH] docs: add chat mode guidance --- Agents.md | 27 +++++++++++++++++++++++++++ PRD.md | 1 + README.md | 5 +++-- docs/ai/cross-platform.md | 9 +++++++++ docs/ai/overview.md | 11 +++++++++++ docs/ai/usage-tokens.md | 9 +++++++++ docs/planning/AI-Docs-Plan.md | 1 + 7 files changed, 61 insertions(+), 2 deletions(-) diff --git a/Agents.md b/Agents.md index 11ed457..b871084 100644 --- a/Agents.md +++ b/Agents.md @@ -25,6 +25,33 @@ Keep this file aligned with PRD, README, and docs/planning/AI-Docs-Plan.md when - Plan a refactor before making edits. - Summarize and assess risks across files. +## Chat Types In Copilot (Ask, Edit, Agent, Plan) +These are the four ways you can run a Copilot chat. Pick the lightest mode that matches the job. + +### Ask +Use this for questions, explanations, summaries, or quick guidance. It does not change files. + +Example: +"Explain what this function does and list the top 3 risks." + +### Edit +Use this for small, specific file edits with clear constraints. + +Example: +"In this file, rename `UserProfile` to `AccountProfile` and update all references. Do not change behavior." + +### Plan +Use this to get a step-by-step plan before any edits happen. + +Example: +"Give me a 5-step plan to refactor this module. Wait for approval before making changes." + +### Agent +Use this for multi-step tasks that span files, require checks, or need a structured workflow. + +Example: +"Refactor these three files to remove duplication, update tests, then summarize the changes and test results." + ## How to Use Agents 1. Define the outcome in one sentence. 2. List inputs (files, context, constraints). diff --git a/PRD.md b/PRD.md index 0b103ab..3ccf396 100644 --- a/PRD.md +++ b/PRD.md @@ -42,6 +42,7 @@ Teams need a clear, zero-knowledge onboarding path for AI tools, setup, and usag - Assume readers are new to AI. - Use step-by-step instructions and plain language. - Provide examples for key workflows. +- Explain chat modes (Ask, Edit, Plan, Agent) with concrete examples. ## Definition Of Done (Doc Updates) - New markdown files are linked in docs/ai/index.md. diff --git a/README.md b/README.md index 91daa38..97661fd 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,9 @@ These docs assume the reader is new to AI. Be explicit, explain terms, and inclu ## How to Use 1. Start at the [AI Docs Index](docs/ai/index.md). -2. Follow the iOS or Android setup guide. -3. Review skills and token usage guidance. +2. Read the overview to learn chat modes (Ask, Edit, Plan, Agent). +3. Follow the iOS or Android setup guide. +4. Review skills and token usage guidance. ## Local Workflow - Edit files in docs/ai. diff --git a/docs/ai/cross-platform.md b/docs/ai/cross-platform.md index 4035ed0..7a514ac 100644 --- a/docs/ai/cross-platform.md +++ b/docs/ai/cross-platform.md @@ -22,6 +22,15 @@ Verification: No tests needed - Use agents for multi-step tasks like refactors, doc audits, or migrations. - Use chat for quick questions or one-off explanations. +## Chat Modes In Copilot +Ask: Quick Q and A or summaries. Example: "Explain this error message and list the top 3 likely fixes." + +Edit: Targeted file edits with constraints. Example: "In this file, extract a helper function for validation and keep behavior the same." + +Plan: Planning only, no edits yet. Example: "Provide a 5-step plan to split this class into smaller components. Wait for approval." + +Agent: Multi-step work across files or tools. Example: "Refactor the service layer, update tests, run the test task, and summarize results." + ### Request Template Use this structure to get consistent results: diff --git a/docs/ai/overview.md b/docs/ai/overview.md index 6e88ec1..fc72878 100644 --- a/docs/ai/overview.md +++ b/docs/ai/overview.md @@ -48,6 +48,17 @@ 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. +## Chat Types In Plain English +Copilot chat has four modes. Pick the smallest one that fits the task. + +Ask: Quick questions, summaries, or explanations. Example: "Summarize this file in 5 bullets and list 2 risks." + +Edit: Small, specific changes with constraints. Example: "Update this function to return nil when the input is empty. Keep behavior the same otherwise." + +Plan: A step-by-step plan before edits. Example: "Give me a 6-step plan to add caching to this service. Wait for approval before edits." + +Agent: Multi-step work across files with checks. Example: "Refactor these two files, update unit tests, then summarize the changes and test results." + ### Example: Chat vs Agents - Chat: "What does this function do?" - Agent: "Plan and refactor this module, then list tests to add." diff --git a/docs/ai/usage-tokens.md b/docs/ai/usage-tokens.md index b983f1c..eb5c1da 100644 --- a/docs/ai/usage-tokens.md +++ b/docs/ai/usage-tokens.md @@ -135,6 +135,15 @@ If each step is done with a 3x model and a growing chat context, your token use - Standardize request templates. - Agree on when to use agents vs chat. +### Use The Right Chat Mode +Using the lightest chat mode for the job keeps outputs smaller and cheaper. + +Example: +Ask: "Summarize this file in 5 bullets." +Plan: "Give me a 5-step plan to refactor this module. Wait for approval." +Edit: "Update this function to handle empty input. Keep behavior the same otherwise." +Agent: "Refactor these two files, update tests, and summarize results." + ## Quick Checklist - Is the request specific and scoped? - Do I need the whole file or just a section? diff --git a/docs/planning/AI-Docs-Plan.md b/docs/planning/AI-Docs-Plan.md index c82b849..326c406 100644 --- a/docs/planning/AI-Docs-Plan.md +++ b/docs/planning/AI-Docs-Plan.md @@ -7,6 +7,7 @@ Keep the planning view of the docs hierarchy, scope, and future work. This is a - Assume readers are new to AI. - Use step-by-step instructions. - Provide at least one example per major section. +- Explain chat modes (Ask, Edit, Plan, Agent) in plain language with examples. ## Current Docs Location - docs/ai/