mbrucedogs/ai-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: standardize example formatting

Browse Source
This commit is contained in:
Matt Bruce 2026-02-10 15:50:59 -06:00
parent fb15105d87
commit 15ad82b644
11 changed files with 188 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
Agents.md
View File

@ -9,6 +9,7 @@ Assume the reader is new to AI and needs detailed, step-by-step guidance.
- Be specific and explicit. Avoid shorthand.
- Explain terms in plain language.
- Provide an example whenever possible.
- Format chat or code examples consistently: use "Example prompt:" with a fenced ```text``` block for chat prompts, and "Example code:" with the right language for code.
- Prefer checklists, short steps, and concrete outcomes.
- Assume the reader is an expert engineer but a beginner at AI.
@ -48,13 +49,19 @@ If you had to restart a chat and re-explain the goal, add a short reminder so th
- "If placement is unclear, ask where the content should live before editing."
### Example Request
"Read Agents.md and PRD.md first. Propose a plan. Then add chat mode guidance to docs/ai/usage-tokens.md (reader-facing) with hard examples. Do not add reader content to Agents.md."
Example prompt:
```text
Read Agents.md and PRD.md first. Propose a plan. Then add chat mode guidance to docs/ai/usage-tokens.md (reader-facing) with hard examples. Do not add reader content to Agents.md.
```
## Commit And Push After Repo Updates
If you update any file in this repo, commit and push right away so other developers do not lose their local changes. If you are unsure, ask and confirm before pushing.
### Example Request
"Read Agents.md and PRD.md first. Propose a plan, then update docs/ai/ios.md with step-by-step guidance and examples. If you add new files, update docs/ai/index.md."
Example prompt:
```text
Read Agents.md and PRD.md first. Propose a plan, then update docs/ai/ios.md with step-by-step guidance and examples. If you add new files, update docs/ai/index.md.
```
## Skills Sync
This repo uses a skills manifest to standardize skills across developers.
@ -70,7 +77,10 @@ This repo uses a skills manifest to standardize skills across developers.
- Verification: (tests or checks)
## Example
Example request:
```text
Goal: Add a troubleshooting section to the AI docs.
Inputs: docs/ai/troubleshooting.md, docs/planning/AI-Docs-Plan.md
Output: Updated troubleshooting section with 5 common issues.
Verification: Manual review.
```

5
README.md
View File

@ -34,7 +34,10 @@ These docs assume the reader is new to AI. Be explicit, explain terms, and inclu
- 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."
Example prompt:
```text
Add a new skill link to docs/ai/skills.md and include a 2-sentence description.
```
## Next Steps
- Add screenshots and short walkthrough videos.

15
docs/ai/android.md
View File

@ -14,6 +14,7 @@
### Example Prompt (VS Code)
Open a Kotlin file and add:
Example prompt:
```text
// Create a Kotlin data class for a user profile with name and email.
```
@ -29,7 +30,10 @@ Open a Kotlin file and add:
- 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."
Example prompt:
```text
Refactor this repository to reduce duplication. Keep the public API the same and list tests to update.
```
## MCP For Android (High-Level)
MCP tools can automate Android tasks like builds, tests, and diagnostics. The exact tool depends on your team setup.
@ -41,9 +45,12 @@ When you identify the approved Android MCP tool(s), add:
- Example prompts
### Starter Prompts
- "Create a Kotlin data class and mapper for this API response."
- "Write unit tests for this repository using JUnit."
- "Refactor this file to reduce duplication without changing behavior."
Example prompts:
```text
Create a Kotlin data class and mapper for this API response.
Write unit tests for this repository using JUnit.
Refactor this file to reduce duplication without changing behavior.
```
## Android Troubleshooting
- If suggestions are missing, confirm sign-in and access.

51
docs/ai/cross-platform.md
View File

@ -10,6 +10,7 @@ Agents define a structured workflow so tasks are broken into clear steps, with e
3. Provide the inputs in a short, bounded request.
### Example Request
Example prompt:
```text
Goal: Improve readability in this module
@ -23,13 +24,18 @@ Verification: No tests needed
- 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."
Ask: Quick Q and A or summaries.
Edit: Targeted file edits with constraints.
Plan: Planning only, no edits yet.
Agent: Multi-step work across files or tools.
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."
Example prompts:
```text
Ask: Explain this error message and list the top 3 likely fixes.
Edit: In this file, extract a helper function for validation and keep behavior the same.
Plan: Provide a 5-step plan to split this class into smaller components. Wait for approval.
Agent: Refactor the service layer, update tests, run the test task, and summarize results.
```
### Request Template
Use this structure to get consistent results:
@ -42,14 +48,20 @@ Verification: <tests or checks>
```
## Prompting Patterns
- Refactors: "Refactor this file to improve readability without changing behavior."
- Tests: "Add unit tests for this service. Keep the existing public API."
- Debugging: "Explain this error and list likely fixes in order."
- Understanding code: "Summarize what this module does and call out risks."
Example prompts:
```text
Refactors: Refactor this file to improve readability without changing behavior.
Tests: Add unit tests for this service. Keep the existing public API.
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."
Example prompts:
```text
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.
@ -58,7 +70,10 @@ Scoped: "Refactor this file to remove duplication. Do not change behavior."
4. Verify with tests or review.
### Example Plan Request
"Provide a 5-step plan to refactor this module. Wait for approval before edits."
Example prompt:
```text
Provide a 5-step plan to refactor this module. Wait for approval before edits.
```
## Connecting Skills
- Use skills for tasks with known workflows.
@ -71,7 +86,10 @@ Scoped: "Refactor this file to remove duplication. Do not change behavior."
- 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."
Example prompt:
```text
Summarize the decisions so far in 6 bullets so I can start a new chat.
```
## MCP (Model Context Protocol) - Cross-Platform Overview
MCP is an open standard that lets tools and agents interact with real systems. In plain language, MCP lets the assistant "do" things (like run builds or fetch logs) instead of just talking about them.
@ -91,7 +109,10 @@ Think of MCP as a set of safe, structured buttons the assistant can press. You a
3. You ask for a summary and next steps.
### Example Prompt
"Use the build MCP tool to run the build and summarize any errors."
Example prompt:
```text
Use the build MCP tool to run the build and summarize any errors.
```
### Where To Learn More
- iOS examples: see [iOS Setup](ios.md)

19
docs/ai/governance.md
View File

@ -14,8 +14,11 @@
- Non-approved proprietary information.
## Safe Prompt Examples
- "Summarize this public API and propose tests."
- "Refactor this function without changing behavior."
Example prompts:
```text
Summarize this public API and propose tests.
Refactor this function without changing behavior.
```
## Redaction Tips
- Remove secrets before pasting.
@ -23,8 +26,11 @@
- Use minimal context required for the task.
### Example Redaction
Before: "User ID 928374 has email jane@company.com and token ABC123."
After: "User ID <USER_ID> has email <EMAIL> and token <TOKEN>."
Example:
```text
Before: User ID 928374 has email jane@company.com and token ABC123.
After: User ID <USER_ID> has email <EMAIL> and token <TOKEN>.
```
## Compliance Expectations
- Follow org security policies and data handling rules.
@ -34,4 +40,7 @@ After: "User ID <USER_ID> has email <EMAIL> and token <TOKEN>."
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?"
Example prompt:
```text
Is it ok to share this log snippet with user IDs in Copilot?
```

45
docs/ai/ios-xcodebuildmcp.md
View File

@ -13,9 +13,12 @@ Common uses include:
- Capture build output so the assistant can summarize errors
### Example Requests
- "Use XcodeBuildMCP to build the app and summarize any errors."
- "Run tests with XcodeBuildMCP and list the failing tests."
- "Build with XcodeBuildMCP and extract the first error message."
Example prompts:
```text
Use XcodeBuildMCP to build the app and summarize any errors.
Run tests with XcodeBuildMCP and list the failing tests.
Build with XcodeBuildMCP and extract the first error message.
```
## What It Can Do (Detailed Examples)
Below are common tasks and how to ask for them. Adjust the wording to match your project.
@ -23,32 +26,42 @@ Below are common tasks and how to ask for them. Adjust the wording to match your
### Build
Goal: Run a build and get a short error summary.
Example:
"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."
Example prompt:
```text
Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets.
```
### Unit Tests
Goal: Run unit tests and list failures.
Example:
"Run unit tests with XcodeBuildMCP and list failing tests with file names."
Example prompt:
```text
Run unit tests with XcodeBuildMCP and list failing tests with file names.
```
### UI Tests
Goal: Run UI tests on a known simulator.
Example:
"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."
Example prompt:
```text
Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures.
```
### Screenshots (UI Testing)
Goal: Trigger a UI test that captures screenshots and then list the generated images.
Example:
"Run the UI test that captures screenshots and list the output paths."
Example prompt:
```text
Run the UI test that captures screenshots and list the output paths.
```
### Build Output Parsing
Goal: Extract the first error for quick diagnosis.
Example:
"Build with XcodeBuildMCP and extract the first error message only."
Example prompt:
```text
Build with XcodeBuildMCP and extract the first error message only.
```
## Xcode 26.3 MCP Setup (Detailed)
These steps reflect a common setup as of February 2026. Wording may vary slightly in release candidates.
@ -109,8 +122,10 @@ Add to VS Code:
2. Use Copilot Chat in agent mode for multi-step tasks.
3. MCP tools appear as slash commands once discovered.
Example:
"Use XcodeBuildMCP to build and summarize errors. Then suggest fixes."
Example prompt:
```text
Use XcodeBuildMCP to build and summarize errors. Then suggest fixes.
```
### Tips And Caveats
- Xcode must be running (or launchable) for MCP tools to respond.

16
docs/ai/ios.md
View File

@ -14,6 +14,7 @@
### Example Prompt (Xcode)
Type this in a Swift file comment, then wait for a suggestion:
Example prompt:
```text
// Create a function that validates an email string.
```
@ -38,6 +39,7 @@ Type this in a Swift file comment, then wait for a suggestion:
### Example Prompt (VS Code)
Open a Swift file and add:
Example prompt:
```text
// Create a Swift struct for a user profile with name and email.
```
@ -53,12 +55,18 @@ Open a Swift file and add:
- 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."
Example prompt:
```text
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."
- "Refactor this view to reduce duplication without changing behavior."
Example prompts:
```text
Create a SwiftUI view model for this screen and list its inputs and outputs.
Write unit tests for this view model using XCTest.
Refactor this view to reduce duplication without changing behavior.
```
## MCP For iOS
The detailed MCP setup and XcodeBuildMCP guidance is in a dedicated page:

36
docs/ai/overview.md
View File

@ -14,8 +14,11 @@ AI tools help with drafting, refactoring, explaining code, and accelerating rout
- 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.)
Example prompts:
```text
Good: Summarize this file and list the top 3 risks.
Risky: Rewrite this subsystem without review.
```
## GitHub Copilot Enterprise
### What It Is
@ -91,17 +94,25 @@ Project example: See [README.md](../../README.md) for the start-here links and l
## 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."
Ask: Quick questions, summaries, or explanations.
Edit: Small, specific changes with constraints.
Plan: A step-by-step plan before edits.
Agent: Multi-step work across files with checks.
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 prompts:
```text
Ask: Summarize this file in 5 bullets and list 2 risks.
Edit: Update this function to return nil when the input is empty. Keep behavior the same otherwise.
Plan: Give me a 6-step plan to add caching to this service. Wait for approval before edits.
Agent: 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."
Example prompts:
```text
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:
@ -117,7 +128,10 @@ Summarize what this file does in 3 bullet points.
- 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."
Example prompt:
```text
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.

10
docs/ai/skills.md
View File

@ -12,7 +12,10 @@ Skills are reusable instructions and workflows that guide the assistant through
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?"
Example prompt:
```text
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.
@ -61,7 +64,10 @@ skills:
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."
Example prompt:
```text
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.

12
docs/ai/troubleshooting.md
View File

@ -31,8 +31,11 @@
- Provide a small example or expected output.
### Example Fix
Bad: "Fix this."
Better: "Refactor this function to remove duplication. Keep behavior the same."
Example prompts:
```text
Bad: Fix this.
Better: Refactor this function to remove duplication. Keep behavior the same.
```
## What To Collect Before Escalation
- Editor version and plugin version.
@ -40,7 +43,10 @@ Better: "Refactor this function to remove duplication. Keep behavior the same."
- 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."
Example note:
```text
Copilot suggestions stopped in VS Code 1.92 after extension update. Restarted, still broken. Screenshot attached.
```
## When to Escalate
- Account access issues after setup.

39
docs/ai/usage-tokens.md
View File

@ -27,7 +27,11 @@ Each chat keeps a running memory of what you said. That memory grows over time a
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."
1. In the long chat, ask:
```text
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.
@ -94,9 +98,12 @@ Refactor these two files, update tests, run the test task, and summarize results
```
### 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.
Example prompts:
```text
Summarize this file in 5 bullets. -> Use a 0.33x or 1x model.
Refactor three files and update tests. -> Start with a 1x model. Move to 3x only if the 1x model fails.
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.
@ -110,14 +117,19 @@ Refactor these two files, update tests, run the test task, and summarize results
- 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."
Example prompts:
```text
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."
- "List risks in this change and suggest tests to add."
Example prompts:
```text
Summarize this file in 5 bullets. Then propose a refactor plan.
Update only the functions in this file that handle validation.
List risks in this change and suggest tests to add.
```
## Daily and Monthly Budgeting Tips
- Batch related questions in a single prompt.
@ -136,8 +148,11 @@ Better: "Only refactor the validation functions in this module. Keep existing be
- 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."
Example prompts:
```text
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