# AI Overview

## Start Here
AI tools help with drafting, refactoring, explaining code, and accelerating routine tasks. They are not a replacement for engineering judgment, security review, or domain knowledge.

## What To Expect In The First 30 Minutes
1. Confirm you have access to GitHub Copilot Enterprise.
2. Install the editor plugin for your platform.
3. Run a simple prompt to verify suggestions appear.
4. Read the usage and token guidance to avoid accidental overuse.

## 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.

### 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.

### Access Requirements
- You must be provisioned for Copilot Enterprise by the org.
- You must sign in with your GitHub account that has access.

### Setup Steps (High-Level)
1. Confirm access with your team or admin.
2. Sign in to GitHub in your editor or plugin.
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.
- Copilot is enabled in the editor or plugin settings.

## Terminology
- Copilot: The AI assistant integrated into your editor.
- Chat: The conversational interface in your editor.
- Agents: Structured workflows that break work into steps.
- Skills: Reusable knowledge or workflows the assistant can apply.
- Tokens: The usage units that track AI consumption.

## 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.

### Agents.md
What it is: The workflow rules for using AI in this repo.

Why you create it: It keeps requests consistent so changes are scoped, reviewable, and repeatable.

What to include:
- Request structure (goal, inputs, output, verification).
- Plan-first guidance for multi-step changes.
- Sync rule: keep PRD.md and README.md aligned when workflows or scope change.

Project example: See [Agents.md](../../Agents.md) for the request template and contribution workflow used in this repo.

### PRD.md
What it is: The product requirements for the documentation set.

Why you create it: It anchors scope and success metrics so the docs do not drift.

What to include:
- Problem statement, goals, and non-goals.
- Target audience and user stories.
- Content requirements (step-by-step guidance and examples).
- Definition of done and sync expectations.

Project example: See [PRD.md](../../PRD.md) for the requirements and definition of done used here.

### README.md
What it is: The entry point for contributors and readers who need quick orientation.

Why you create it: It tells people what the repo is, where to start, and how to contribute.

What to include:
- Repo purpose and audience.
- Where to start (index, overview, setup guides).
- Contribution habits and publishing steps.

Project example: See [README.md](../../README.md) for the start-here links and local workflow.

## 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."

## First Prompt (Safe)
Try a small, safe prompt to confirm everything is working:

```text
Summarize what this file does in 3 bullet points.
```

## Guardrails And Good Habits
- Keep prompts scoped to a single task.
- Ask for a plan before large changes.
- 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).