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

More refactoring

Browse Source 
Signed-off-by: Matt Bruce <matt.bruce1@toyota.com>
This commit is contained in:
Matt Bruce 2026-02-22 15:02:58 -06:00
parent 6b7455f6ff
commit 3586f39e8e
16 changed files with 236 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/ai/android/android.md
View File

@ -53,6 +53,6 @@ Refactor this file to reduce duplication without changing behavior.
- Multiple AI extensions competing for suggestions.
## Next Steps
- For workflow patterns, read [Cross-Platform AI Usage](../cross-platform.md).
- For workflow patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md).
- For safety rules, read [Governance, Privacy, and Policy](../governance.md).
- For cost guidance, read [Usage and Token Budgeting](../usage-tokens.md).

19
docs/ai/crossplatform/cross-platform.md
View File

@ -2,6 +2,15 @@
You are here: [AI Docs Home](../index.md) > Cross-Platform AI Usage
## Contents
- What This Section Covers
- Quick Links
- Repo Instructions (Always-On Rules)
- Agents and Skills
- Example Starting Prompt
- Next Steps
## What This Section Covers
This page gives a high-level overview of cross-platform AI usage, agent workflows, and prompting patterns. For detailed patterns, anti-patterns, and workflows, see the linked guides below.
## Quick Links
@ -12,12 +21,18 @@ This page gives a high-level overview of cross-platform AI usage, agent workflow
- [MCP Overview](mcp-overview.md)
## Repo Instructions (Always-On Rules)
Instructions are repo-scoped rules that auto-apply based on file patterns. See your repo’s instructions directory (e.g., [assets/instructions/](../../assets/instructions/)).
Instructions are repo-scoped rules that auto-apply based on file patterns. See your repo’s instructions directory (e.g., [assets/instructions/](../../../assets/instructions/)).
## Agents and Skills
- Agents: Use for multi-step, structured tasks (see [Agents.md](../../Agents.md)).
- Agents: Use for multi-step, structured tasks (see [Agents.md](../../../Agents.md)).
- Skills: Use for focused, repeatable workflows (see [Skills Library](../skills.md)).
## Example Starting Prompt
Example prompt:
```text
I need to refactor this file safely. First, provide a 5-step plan. Wait for approval before editing.
```
## Next Steps
- For safety rules, read [Governance, Privacy, and Policy](../governance.md)
- If setup is not working, follow [Troubleshooting and FAQ](../troubleshooting.md)

17
docs/ai/crossplatform/mcp-overview.md
View File

@ -1,5 +1,15 @@
# MCP (Model Context Protocol) - Cross-Platform Overview
You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > MCP Overview
## Contents
- What MCP Is
- How MCP Helps In A Workflow
- Common MCP Use Cases
- Example Workflow
- Example Prompt
- Where To Learn More
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.
## How MCP Helps In A Workflow
@ -17,8 +27,15 @@ 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
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/ios.md)
- Android examples: see [Android Setup](../android/android.md)
## Next Steps
- Return to [Cross-Platform AI Usage](cross-platform.md).
- Continue to [Plan-First Workflow](plan-first-workflow.md) for safer multi-step changes.

29
docs/ai/crossplatform/plan-first-workflow.md
View File

@ -1,10 +1,35 @@
# Plan-First Workflow
You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Plan-First Workflow
## Contents
- When To Use Plan-First
- Workflow Steps
- Example Plan Request
- Example Follow-Up Request
- Next Steps
## When To Use Plan-First
Use this workflow when a task is multi-step, risky, or touches more than one file.
## Workflow Steps
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
## Example Plan Request
Example prompt:
```text
Provide a 5-step plan to refactor this module. Wait for approval before edits.
```
## Example Follow-Up Request
Example prompt:
```text
Proceed with steps 1 and 2 only. Show changed files and test results.
```
## Next Steps
- Use [Starter Prompts](starter-prompts.md) for copy/paste prompt options.
- Review [Prompting Patterns](prompting-patterns.md) for prompt structure.

55
docs/ai/crossplatform/prompting-antipatterns.md
View File

@ -1,17 +1,52 @@
# Prompting Anti-Patterns (And Fixes)
Common mistakes and better alternatives:
You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Prompting Anti-Patterns
**Too broad:** Fix everything in this project.
**Better:** Refactor this file to remove duplication. Do not change behavior.
## Contents
- Why Anti-Patterns Cause Rework
- Common Anti-Patterns and Fixes
- Quick Self-Check Before Sending
- Next Steps
**Too vague:** Make this code better.
**Better:** Improve naming and add comments only where logic is complex.
## Why Anti-Patterns Cause Rework
Anti-patterns are prompt styles that are too broad or ambiguous. They usually produce low-quality output, extra retries, and higher token use.
**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.
## Common Anti-Patterns and Fixes
Too broad:
```text
Fix everything in this project.
```
Better:
Example prompt:
```text
Refactor this file to remove duplication. Do not change behavior.
```
### Example: Too Broad vs Scoped
Too vague:
```text
Make this code better.
```
Better:
Example prompt:
```text
Improve naming and add comments only where logic is complex.
```
Too broad: Fix everything in this project.
Scoped: Refactor this file to remove duplication. Do not change behavior.
Missing inputs:
```text
Update the service to handle retries.
```
Better:
Example prompt:
```text
Update ServiceA in src/service/ServiceA.kt to retry 2 times on 5xx. Keep API the same.
```
## Quick Self-Check Before Sending
1. Did I name the exact file or function?
2. Did I say what must not change?
3. Did I ask for one clear output type?
## Next Steps
- Read [Prompting Patterns](prompting-patterns.md) for reusable templates.
- Use [Plan-First Workflow](plan-first-workflow.md) for larger changes.

55
docs/ai/crossplatform/prompting-patterns.md
View File

@ -1,8 +1,53 @@
# Prompting Patterns
Example prompts:
You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Prompting Patterns
- Refactor this file to improve readability without changing behavior.
- Add unit tests for this service. Keep the existing public API.
- Explain this error and list likely fixes in order.
- Summarize what this module does and call out risks.
## Contents
- Why Prompt Patterns Matter
- Prompt Template
- Common Prompt Patterns
- Next Steps
## Why Prompt Patterns Matter
Good prompt patterns reduce rework. They tell the assistant exactly what to change, what not to change, and what output you expect.
## Prompt Template
Use this structure for most requests:
1. Goal: The specific outcome you want.
2. Scope: The file or function to change.
3. Constraints: What must stay the same.
4. Output: What you want returned (code only, bullets, tests, and so on).
Example prompt:
```text
Goal: Refactor validation logic for readability.
Scope: Only ValidationService.swift.
Constraints: Keep behavior and public API unchanged.
Output: Return code changes and a short list of tests to update.
```
## Common Prompt Patterns
- Refactor safely:
Example prompt:
```text
Refactor this file to improve readability without changing behavior.
```
- Add tests:
Example prompt:
```text
Add unit tests for this service. Keep the existing public API.
```
- Debug:
Example prompt:
```text
Explain this error and list likely fixes in priority order.
```
- Understand code:
Example prompt:
```text
Summarize what this module does and call out the top 3 risks.
```
## Next Steps
- Read [Prompting Anti-Patterns](prompting-antipatterns.md) to avoid common mistakes.
- Use [Starter Prompts](starter-prompts.md) when you need copy/paste examples.

54
docs/ai/crossplatform/starter-prompts.md
View File

@ -1,9 +1,51 @@
# Starter Prompts (Copy/Paste)
Use these when you are not sure where to begin:
You are here: [AI Docs Home](../index.md) > [Cross-Platform AI Usage](cross-platform.md) > Starter Prompts
- 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.
## Contents
- How To Use Starter Prompts
- Understand Existing Code
- Safe Refactoring
- Testing
- Planning
- Debugging
- Next Steps
## How To Use Starter Prompts
1. Copy one prompt that matches your task.
2. Replace placeholders (file names, functions, constraints).
3. Keep the request focused on one outcome.
## Understand Existing Code
Example prompt:
```text
Summarize this file in 5 bullets and list 2 risks.
```
## Safe Refactoring
Example prompt:
```text
Refactor this function to remove duplication. Keep behavior the same.
```
## Testing
Example prompt:
```text
List tests I should add for this change.
```
## Planning
Example prompt:
```text
Create a 5-step plan to split this class into smaller components. Wait for approval before edits.
```
## Debugging
Example prompt:
```text
Explain this error and propose the top 3 fixes in priority order.
```
## Next Steps
- Learn stronger prompt structure in [Prompting Patterns](prompting-patterns.md).
- Avoid common mistakes in [Prompting Anti-Patterns](prompting-antipatterns.md).

2
docs/ai/governance.md
View File

@ -58,5 +58,5 @@ Is it ok to share this log snippet with user IDs in Copilot?
```
## Next Steps
- For day-to-day workflows, read [Cross-Platform AI Usage](cross-platform.md).
- For day-to-day workflows, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
- For cost guidance, read [Usage and Token Budgeting](usage-tokens.md).

4
docs/ai/index.md
View File

@ -18,10 +18,10 @@ Follow the steps in order. Do not skip ahead if this is your first time.
1. Read [AI Overview](overview.md)
2. Follow [iOS Setup](ios/ios.md)
3. Skim [Usage and Token Budgeting](usage-tokens.md)
4. Return to [Cross-Platform AI Usage](cross-platform.md)
4. Return to [Cross-Platform AI Usage](crossplatform/cross-platform.md)
## Guided Paths (Pick One)
- New to AI: [AI Overview](overview.md) -> [Cross-Platform AI Usage](cross-platform.md) -> [Usage and Token Budgeting](usage-tokens.md)
- New to AI: [AI Overview](overview.md) -> [Cross-Platform AI Usage](crossplatform/cross-platform.md) -> [Usage and Token Budgeting](usage-tokens.md)
- iOS setup: [AI Overview](overview.md) -> [iOS Setup](ios/ios.md) -> [MCP](ios/ios-mcp.md)
- Android setup: [AI Overview](overview.md) -> [Android Setup](android/android.md)
- Contributors: [AI Overview](overview.md) -> [Governance, Privacy, and Policy](governance.md) -> [Troubleshooting and FAQ](troubleshooting.md)

2
docs/ai/ios/ios-xcodebuildmcp-vscode.md
View File

@ -142,4 +142,4 @@ Common tool actions the agent will use:
## Next Steps
- For iOS setup basics, read [iOS Setup](ios.md).
- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).
- For cross-platform usage patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md).

2
docs/ai/ios/ios-xcodebuildmcp-xcode.md
View File

@ -146,4 +146,4 @@ https://www.apple.com/newsroom/2026/02/xcode-26-point-3-unlocks-the-power-of-age
## Next Steps
- For iOS setup basics, read [iOS Setup](ios.md).
- For cross-platform usage patterns, read [Cross-Platform AI Usage](../cross-platform.md).
- For cross-platform usage patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md).

2
docs/ai/ios/ios.md
View File

@ -42,6 +42,6 @@ You are here: [AI Docs Home](../index.md) > iOS Setup
---
## Next Steps
- For cross-platform patterns, read [Cross-Platform AI Usage](../cross-platform.md)
- For cross-platform patterns, read [Cross-Platform AI Usage](../crossplatform/cross-platform.md)
- For automation, see the MCP guides above
- For safety rules, read [Governance, Privacy, and Policy](../governance.md)

2
docs/ai/overview.md
View File

@ -212,7 +212,7 @@ Refactor only the validation logic in this file. Keep behavior the same and list
## Next Steps
- If you have not set up an editor yet, go to [iOS Setup](ios/ios.md) or [Android Setup](android/android.md).
- For day-to-day usage patterns, read [Cross-Platform AI Usage](cross-platform.md).
- For day-to-day usage patterns, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
- For safety and cost guidance, read [Governance, Privacy, and Policy](governance.md) and [Usage and Token Budgeting](usage-tokens.md).
## Getting Help

5
docs/ai/skills.md
View File

@ -173,9 +173,8 @@ Everything is installable with one command:
- Curated skill lists (for example, ios-skills.txt, android-skills.txt)
### Link To The Assets Repo
- Repo: (link)
- Repo (current project source): [assets/](../../assets/)
## Next Steps
- For day-to-day workflows, read [Cross-Platform AI Usage](cross-platform.md).
- For day-to-day workflows, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
- For setup issues, follow [Troubleshooting and FAQ](troubleshooting.md).

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

@ -210,5 +210,5 @@ Agent: Refactor these two files, update tests, and summarize results.
- Can I ask for a plan first?
## Next Steps
- For workflow patterns, read [Cross-Platform AI Usage](cross-platform.md).
- For workflow patterns, read [Cross-Platform AI Usage](crossplatform/cross-platform.md).
- For troubleshooting, read [Troubleshooting and FAQ](troubleshooting.md).

29
docs/planning/AI-Docs-Plan.md
View File

@ -21,20 +21,33 @@ The docs under docs/ai map 1:1 to Confluence pages.
3. Android (VS Code)
4. Cross-Platform AI Usage
5. iOS MCP (XcodeBuildMCP)
5. Skills Library
6. Usage and Token Budgeting
7. Troubleshooting and FAQ
8. Governance, Privacy, and Policy
6. Skills Library
7. Usage and Token Budgeting
8. Troubleshooting and FAQ
9. Governance, Privacy, and Policy
## Folder Structure (Current)
- docs/
- ai/
- index.md
- overview.md
- ios.md
- ios-xcodebuildmcp.md
- android/android.md
- cross-platform.md
- vscode-setup.md
- android/
- android.md
- ios/
- ios.md
- ios-mcp.md
- ios-mcp-vscode.md
- ios-xcodebuildmcp-xcode.md
- ios-xcodebuildmcp-vscode.md
- xcodebuildmcp-config.yaml.md
- crossplatform/
- cross-platform.md
- prompting-patterns.md
- prompting-antipatterns.md
- plan-first-workflow.md
- starter-prompts.md
- mcp-overview.md
- skills.md
- usage-tokens.md
- troubleshooting.md