diff --git a/PRD.md b/PRD.md index 70b545b..1ea3b96 100644 --- a/PRD.md +++ b/PRD.md @@ -38,6 +38,11 @@ Teams need a clear, zero-knowledge onboarding path for AI tools, setup, and usag - Skills inventory and usage guidance. - Token usage guidance and troubleshooting. +## Content Requirements +- Assume readers are new to AI. +- Use step-by-step instructions and plain language. +- Provide examples for key workflows. + ## Assumptions - The org has a Copilot Enterprise subscription. - Editors are standard across teams (Xcode and VS Code). diff --git a/README.md b/README.md index e388056..91daa38 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,9 @@ This repo contains the source markdown for a Confluence-ready AI documentation set for mobile development. It is designed to be beginner-friendly and easy to keep current. +## Audience +These docs assume the reader is new to AI. Be explicit, explain terms, and include examples where possible. + ## Structure - [AI Docs Index](docs/ai/index.md) - [Agents](Agents.md) @@ -29,6 +32,9 @@ This repo contains the source markdown for a Confluence-ready AI documentation s - Add platform-specific examples when possible. - Update the Skills Library with repo links. +### Example Change +"Add a new skill link to docs/ai/skills.md and include a 2-sentence description." + ## Next Steps - Add screenshots and short walkthrough videos. - Assign owners per section. diff --git a/docs/ai/android.md b/docs/ai/android.md index 1b9b76b..2467607 100644 --- a/docs/ai/android.md +++ b/docs/ai/android.md @@ -11,6 +11,13 @@ 3. Confirm Copilot is enabled in VS Code. 4. Run a simple prompt to verify suggestions appear. +### Example Prompt (VS Code) +Open a Kotlin file and add: + +```text +// Create a Kotlin data class for a user profile with name and email. +``` + ### Verification Steps - Open a Kotlin file and start a small function. - Confirm inline suggestions appear. @@ -21,6 +28,9 @@ - Request unit tests for services and view models. - Prefer incremental changes over large rewrites. +### Example Request +"Refactor this repository to reduce duplication. Keep the public API the same and list tests to update." + ### Starter Prompts - "Create a Kotlin data class and mapper for this API response." - "Write unit tests for this repository using JUnit." diff --git a/docs/ai/cross-platform.md b/docs/ai/cross-platform.md index e25e619..b0c3033 100644 --- a/docs/ai/cross-platform.md +++ b/docs/ai/cross-platform.md @@ -9,6 +9,15 @@ Agents define a structured workflow so tasks are broken into clear steps, with e 2. Choose a workflow that matches your task. 3. Provide the inputs in a short, bounded request. +### Example Request + +```text +Goal: Improve readability in this module +Inputs: src/foo/Bar.kt, keep behavior the same +Output: A small refactor and a short summary +Verification: No tests needed +``` + ### When to Use Agents vs Chat - Use agents for multi-step tasks like refactors, doc audits, or migrations. - Use chat for quick questions or one-off explanations. @@ -29,12 +38,19 @@ Verification: - Debugging: "Explain this error and list likely fixes in order." - Understanding code: "Summarize what this module does and call out risks." +### Example: Too Broad vs Scoped +Too broad: "Fix everything in this project." +Scoped: "Refactor this file to remove duplication. Do not change behavior." + ## Plan-First Workflow 1. Ask for a short plan. 2. Approve or adjust the plan. 3. Ask for targeted changes. 4. Verify with tests or review. +### Example Plan Request +"Provide a 5-step plan to refactor this module. Wait for approval before edits." + ## Connecting Skills - Use skills for tasks with known workflows. - Combine multiple skills when a task spans domains. @@ -44,3 +60,6 @@ Verification: - Keep prompts small and scoped. - Reuse context from earlier steps instead of repeating it. - Ask for summaries before asking for edits. + +### Example Summary Request +"Summarize the decisions so far in 6 bullets so I can start a new chat." diff --git a/docs/ai/governance.md b/docs/ai/governance.md index bb0f378..6817b46 100644 --- a/docs/ai/governance.md +++ b/docs/ai/governance.md @@ -22,9 +22,16 @@ - Replace real identifiers with placeholders. - Use minimal context required for the task. +### Example Redaction +Before: "User ID 928374 has email jane@company.com and token ABC123." +After: "User ID has email and token ." + ## Compliance Expectations - Follow org security policies and data handling rules. - Use AI as assistance, not authority. ## Ownership If you are unsure about data classification, escalate before using AI. + +### Example Question +"Is it ok to share this log snippet with user IDs in Copilot?" diff --git a/docs/ai/index.md b/docs/ai/index.md index f059015..9eb488c 100644 --- a/docs/ai/index.md +++ b/docs/ai/index.md @@ -2,6 +2,18 @@ Welcome. This section is the entry point for AI enablement. It assumes no prior knowledge and is safe to follow step-by-step. +## Who This Is For +You can be an expert engineer and still be new to AI. This guide explains every step and includes examples to keep you from guessing. + +## How To Use This Guide +Follow the steps in order. Do not skip ahead if this is your first time. + +### Example Path (New iOS Engineer) +1. Read [AI Overview](overview.md) +2. Follow [iOS Setup](ios.md) +3. Skim [Usage and Token Budgeting](usage-tokens.md) +4. Return to [Cross-Platform AI Usage](cross-platform.md) + ## If You Are New 1. Read the overview to understand terms and guardrails. 2. Follow the setup guide for your platform. diff --git a/docs/ai/ios.md b/docs/ai/ios.md index f393df3..475042f 100644 --- a/docs/ai/ios.md +++ b/docs/ai/ios.md @@ -11,6 +11,13 @@ 3. Confirm Copilot is enabled in Xcode. 4. Run a simple prompt to verify suggestions appear. +### Example Prompt (Xcode) +Type this in a Swift file comment, then wait for a suggestion: + +```text +// Create a function that validates an email string. +``` + ### Verification Steps - Open a Swift file and start a small function. - Confirm inline suggestions appear. @@ -28,6 +35,13 @@ 3. Confirm Copilot is enabled in VS Code. 4. Run a simple prompt to verify suggestions appear. +### Example Prompt (VS Code) +Open a Swift file and add: + +```text +// Create a Swift struct for a user profile with name and email. +``` + ### Verification Steps - Open a Swift file and type a short function signature. - Confirm inline suggestions appear. @@ -38,6 +52,9 @@ - Request tests or sample usages for view models. - Favor refactor or patch requests over full rewrites. +### Example Request +"Refactor this SwiftUI view to reduce duplication. Do not change behavior. Provide a short diff summary." + ### Starter Prompts - "Create a SwiftUI view model for this screen and list its inputs and outputs." - "Write unit tests for this view model using XCTest." diff --git a/docs/ai/overview.md b/docs/ai/overview.md index a10ea06..6e88ec1 100644 --- a/docs/ai/overview.md +++ b/docs/ai/overview.md @@ -13,6 +13,10 @@ AI tools help with drafting, refactoring, explaining code, and accelerating rout - 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. +### Example (Good vs Risky) +Good: "Summarize this file and list the top 3 risks." +Risky: "Rewrite this subsystem without review." (Always review large changes.) + ## GitHub Copilot Enterprise ### What It Is Copilot is an AI coding assistant that integrates with editors and chats to help you write and understand code. @@ -27,6 +31,11 @@ Copilot is an AI coding assistant that integrates with editors and chats to help 3. Verify Copilot is enabled in editor settings. 4. Run a quick prompt to validate it works. +### What You Should See +- A Copilot icon or status indicator in your editor. +- Inline code suggestions as you type. +- A chat panel that can answer questions. + ### Quick Access Checklist - GitHub account is linked to the org. - SSO or required auth flow is completed. @@ -39,6 +48,10 @@ 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. +### Example: Chat vs Agents +- Chat: "What does this function do?" +- Agent: "Plan and refactor this module, then list tests to add." + ## First Prompt (Safe) Try a small, safe prompt to confirm everything is working: @@ -52,6 +65,9 @@ Summarize what this file does in 3 bullet points. - Verify outputs with tests and review. - Avoid sharing secrets or sensitive data. +### Example: Safe Prompt +"Refactor only the validation logic in this file. Keep behavior the same and list tests to update." + ## Getting Help - Ask your team lead or the AI docs owner. - Use the escalation guidance in [Troubleshooting and FAQ](troubleshooting.md). diff --git a/docs/ai/skills.md b/docs/ai/skills.md index f7121d1..5cbdb47 100644 --- a/docs/ai/skills.md +++ b/docs/ai/skills.md @@ -11,6 +11,9 @@ Skills are reusable instructions and workflows that guide the assistant through ## Skills Directory Store skills in the team-approved skills directory for your environment. If you do not know the location, ask your team lead or check your internal setup docs. +### Example Question To Ask +"Where is the approved skills directory for our team, and how do I add a new skill?" + ## Skills Governance And Sync To keep skills consistent across teams, use a central skills registry plus a per-project manifest. Avoid copying skills into every repo unless the skill is tightly coupled to the project. @@ -38,6 +41,11 @@ skills: 2. The script pulls the registry and copies required skills to your local skills directory. 3. Restart your editor if required. +### Example Sync Command +```bash +./scripts/sync-skills.sh +``` + ## How to Download Existing Skills 1. Locate the skill in the team or org repository. 2. Add the skill to your local skills directory following team guidance. @@ -52,6 +60,9 @@ skills: 2. Provide the inputs that skill expects. 3. If needed, add a secondary skill and explain the handoff. +### Example Skill Request +"Use swiftui-expert-skill to review this view for best practices. Then use webapp-testing to validate the web flow." + ## Current Skills (Add Repo Links) Add a short summary and link for each skill below. diff --git a/docs/ai/troubleshooting.md b/docs/ai/troubleshooting.md index 3caf8ed..176b48f 100644 --- a/docs/ai/troubleshooting.md +++ b/docs/ai/troubleshooting.md @@ -5,6 +5,12 @@ - No suggestions: verify Copilot is enabled in the editor. - Plugin missing: confirm the plugin or extension is installed. +### Example: No Suggestions +1. Confirm you are signed in. +2. Confirm the extension is enabled. +3. Open a new file and type a simple prompt. +4. Restart the editor if needed. + ## Quick Diagnostic Flow 1. Confirm account access and SSO. 2. Confirm plugin or extension is installed and enabled. @@ -24,11 +30,18 @@ - Tighten the prompt with scope and context. - Provide a small example or expected output. +### Example Fix +Bad: "Fix this." +Better: "Refactor this function to remove duplication. Keep behavior the same." + ## What To Collect Before Escalation - Editor version and plugin version. - Error messages or screenshots. - Whether the issue is reproducible in another editor. +### Example Escalation Note +"Copilot suggestions stopped in VS Code 1.92 after extension update. Restarted, still broken. Screenshot attached." + ## When to Escalate - Account access issues after setup. - Consistent failures across multiple editors. diff --git a/docs/ai/usage-tokens.md b/docs/ai/usage-tokens.md index d53a879..b983f1c 100644 --- a/docs/ai/usage-tokens.md +++ b/docs/ai/usage-tokens.md @@ -3,12 +3,86 @@ ## How Tokens Are Spent Tokens are consumed based on input length, output length, and tool usage. Long prompts and repeated context increase usage quickly. +### Simple Example +If you paste a large file and ask for a rewrite, you pay for: +1. The pasted file (input tokens) +2. The model reasoning about it +3. The full rewritten output (output tokens) + +If you do that several times in a row, you can burn a large portion of your daily or monthly allowance quickly. + +## Chat Context (Why New Chats Matter) +Each chat keeps a running memory of what you said. That memory grows over time and gets sent back to the model, which costs more tokens and can slow responses. + +### Best Practice +- Start a new chat for each topic or task. +- Do not keep one chat open for weeks and switch subjects. + +### Why This Matters +- Bigger context = more tokens used per message. +- Larger contexts can slow response time. +- Old context can confuse the model and reduce answer quality. + +### Use Summaries To Reset Context +When a chat gets long, ask for a short summary and start a new chat using that summary. This keeps context small and saves tokens. + +#### Example: Resetting A Long Chat +1. In the long chat, ask: "Summarize the current state and decisions in 8 bullets." +2. Copy the summary into a new chat. +3. Continue from there with a smaller context. + +## Model Choice Matters (Plain Language) +Think of each model as a different "speed and cost" setting. Some models are cheap and fast. Some are smarter but cost more for the same question. If you pick a higher-cost model, you can burn through your daily or monthly allowance much faster. + +### Models Available (From The Copilot Picker) +- Auto (10% discount) +- GPT-4.1 (0x) +- GPT-4o (0x) +- GPT-5 mini (0x) +- Grok Code Fast 1 +- Claude Haiku 4.5 (0.33x) +- Claude Opus 4.5 (3x) +- Claude Opus 4.6 (3x) +- Claude Sonnet 4 (1x) +- Claude Sonnet 4.5 (1x) +- Gemini 2.5 Pro (1x) +- Gemini 3 Flash (Preview) (0.33x) +- Gemini 3 Pro (Preview) (1x) +- GPT-5 (1x) +- GPT-5-Codex (Preview) (1x) +- GPT-5.1 (1x) +- GPT-5.1-Codex (1x) +- GPT-5.1-Codex-Max (1x) +- GPT-5.1-Codex-Mini (Preview) (0.33x) +- GPT-5.2 (1x) +- GPT-5.2-Codex (1x) + +### Practical Guidance (Plain Language) +- Use cheaper models for summaries, quick questions, and small edits. +- Use expensive models only when the task is truly complex or high-stakes. +- If you are unsure, start with Auto or a 0.33x or 1x option, then move up only if needed. + +#### Example: Choosing A Model +- Task: "Summarize this file in 5 bullets." Use a 0.33x or 1x model. +- Task: "Refactor three files and update tests." Start with a 1x model. Move to 3x only if the 1x model fails. +- Task: "Explain a confusing production issue with lots of context." Start with 1x, and only move up if needed. + +### Quick Glossary +- Model: The "brain" Copilot uses to answer your question. +- Multiplier: A cost factor. Higher number = faster token usage. +- Tokens: The units that count your AI usage (roughly input + output size). + ## Best Practices to Reduce Usage - Use clear, bounded requests with specific goals. - Prefer targeted edits over full rewrites. - Reuse context by referencing earlier outputs instead of re-pasting. - Ask for summaries before requesting changes. +### Before And After Example +Bad: "Rewrite this entire module and update all tests." + +Better: "Only refactor the validation functions in this module. Keep existing behavior. List tests to update." + ## Examples of Efficient Prompts - "Summarize this file in 5 bullets. Then propose a refactor plan." - "Update only the functions in this file that handle validation." @@ -19,16 +93,43 @@ Tokens are consumed based on input length, output length, and tool usage. Long p - Timebox explorations and stop when enough info is gathered. - Avoid repeated retries without changing the prompt. +### Example: Timeboxed Session +1. Ask for a 5-step plan. +2. Approve or adjust. +3. Ask for just step 1 or 2. +4. Stop and summarize before moving on. + ## Budgeting Routine - Start with a plan-first request for large tasks. - Limit each request to one output type. - End sessions with a short summary for easy follow-up. +### Example: One Output Type +Instead of: "Refactor the file, explain it, and add tests." +Use: "Refactor the file only. Do not explain or add tests." +Then follow up with a separate request if needed. + ## Red Flags That Burn Tokens Quickly - Large file pastes with no clear ask. - Multiple full rewrites in one session. - Repeated "start over" requests. +## How You Can Burn A Full Day Fast (Example Scenarios) +- You paste multiple large files and ask a 3x model to rewrite everything plus tests. +- You keep asking a high-cost model to "start over" with a new approach. +- You do a long debugging session on a big codebase using a 3x model for every step. +- You ask for full architecture diagrams and long explanations from a high-cost model in one session. + +### Realistic "New User" Scenario +You open a single chat and do this all day: +1. Paste a large file and ask for a full rewrite. +2. Ask for a different rewrite using another approach. +3. Ask for full tests. +4. Ask for a full explanation of the changes. +5. Repeat with another file. + +If each step is done with a 3x model and a growing chat context, your token use can spike quickly and slow down responses. + ## Team Habits That Help - Capture reusable prompts in a shared doc. - Standardize request templates. diff --git a/docs/planning/AI-Docs-Plan.md b/docs/planning/AI-Docs-Plan.md index 7e169c0..e73d3cd 100644 --- a/docs/planning/AI-Docs-Plan.md +++ b/docs/planning/AI-Docs-Plan.md @@ -3,6 +3,11 @@ ## Purpose Keep the planning view of the docs hierarchy, scope, and future work. This is a planning artifact, not the published content. +## Audience And Tone +- Assume readers are new to AI. +- Use step-by-step instructions. +- Provide at least one example per major section. + ## Current Docs Location - docs/ai/