# Instruction Optimization — Technique Catalog

Reference companion for the `ao-optimize-instructions` skill. All examples use
a hypothetical **TaskFlow** project (Python/FastAPI task management app) to stay
project-agnostic.

## Technique 1: Section Extraction

**Scenario:** `copilot-instructions.md` has 1,400 lines with a 500-line code
standards section.

**Before:**
```markdown
# copilot-instructions.md

## Code Standards
- Type annotations on all functions (enforced by mypy strict)
- Google-style docstrings on all public APIs
- Use pathlib.Path — no os.path
- Max 20 lines per function
- Line length: 88
{... 480 more lines of conventions, examples, edge cases ...}
```

**After — copilot-instructions.md (summary):**
```markdown
## Code Standards
See: [code-standards.md](.agent/ops/references/code-standards.md)
Key: Type annotations required, Google docstrings, pathlib only, 20-line max.
```

**After — .agent/ops/references/code-standards.md (full content):**
```markdown
---
title: Code Standards
extracted_from: copilot-instructions.md
extracted_date: 2025-01-15
---
# Code Standards
- Type annotations on all functions (enforced by mypy strict)
- Google-style docstrings on all public APIs
{... full original content ...}
```

**Result:** copilot-instructions.md reduced by ~490 lines.

---

## Technique 2: Editor-Specific Path-Scoped Files

**Scenario:** Testing conventions apply only when editing `tests/**`.

**For Copilot — `.github/instructions/tests.instructions.md`:**
```yaml
---
applyTo: "tests/**"
---
# Testing Conventions
- Use pytest with tmp_path for isolation
- Test classes: Test<Feature>, functions: test_<scenario>
- Never import from src directly in conftest
- Integration tests in tests/integration/
```

**For Claude Code — `.claude/rules/testing.md`:**
```yaml
---
paths:
  - "tests/**"
---
# Testing Conventions
- Use pytest with tmp_path for isolation
- Test classes: Test<Feature>, functions: test_<scenario>
```

**Key:** Generate these only for editors the project actually uses.

---

## Technique 3: @-Import Chains (Claude Code)

**Scenario:** Keep `CLAUDE.md` minimal, reference extracted files.

```markdown
# CLAUDE.md — TaskFlow
@.agent/ops/references/code-standards.md
@.agent/ops/references/architecture.md
@.agent/ops/references/testing-conventions.md

## Quick Reference
- Build: make build
- Test: make test
- Deploy: make deploy
```

Claude Code resolves @-imports recursively (up to 5 hops). The inline section
stays short for editors that don't support imports.

---

## Technique 4: Architecture Extraction

**Scenario:** 200-line directory tree with module descriptions.

**Before (inline in copilot-instructions.md):**
```markdown
## Architecture
src/taskflow/
├── api/              # FastAPI routes
│   ├── routes/       # One file per resource
│   ├── deps.py       # Dependency injection
│   └── middleware.py  # Auth, CORS, logging
├── core/             # Business logic
│   ├── services/     # Service layer
│   └── models.py     # SQLAlchemy models
├── infra/            # External integrations
│   ├── db.py         # Database session
│   ├── cache.py      # Redis client
│   └── queue.py      # Celery tasks
└── cli.py            # Typer CLI (thin layer)
{... 180 more lines of module descriptions ...}
```

**After:**
```markdown
## Architecture
See: [architecture.md](.agent/ops/references/architecture.md)
Layout: src/taskflow/ with api/, core/, infra/ layers. CLI is thin wrapper.
```

---

## Technique 5: Duplication Elimination

**Scenario:** Same Python conventions appear in `copilot-instructions.md`,
`AGENTS.md`, and `.cursorrules`.

**Solution:**
1. Extract canonical version to `.agent/ops/references/code-standards.md`
2. In each instruction file, replace with summary + link
3. For editors without link support (Cursor), keep a short inline version

**copilot-instructions.md:**
```markdown
## Code Standards
See: [code-standards.md](.agent/ops/references/code-standards.md)
```

**AGENTS.md:**
```markdown
## Code Standards
See: [code-standards.md](.agent/ops/references/code-standards.md)
```

**.cursorrules (no import support — keep inline summary):**
```markdown
## Code Standards
- Type annotations on all functions
- Google-style docstrings
- pathlib.Path for file ops
- Max 20 lines per function
```

---

## Technique 6: Conditional/Tiered Content

**Scenario:** Quick reference needed inline, full guide available on demand.

```markdown
## Database Migrations

**Quick reference:**
- `make migrate` to apply pending migrations
- `make migrate-create "description"` to create new migration
- Always test migrations with `make migrate-test` before committing

**Full guide:** [migrations.md](.agent/ops/references/migrations.md)
```

---

## Sizing Heuristic

Use this quick estimate to decide whether extraction is worthwhile:

| Section size | Action |
|-------------|--------|
| <20 lines | Keep inline — extraction overhead not worth it |
| 20–50 lines | Consider — extract if duplicated or rarely referenced |
| >50 lines | Extract — clear win for context budget |

**Token estimation:** ~4 tokens per line of markdown (rough average).

---

## Common Pitfalls

| Pitfall | Why it fails | Fix |
|---------|-------------|-----|
| Extract everything | Leaves instruction file too sparse | Keep critical workflow inline |
| Put project content in `.ao/references/` | `.ao/` is framework-agnostic | Use `.agent/ops/references/` |
| Generate files for unused editors | Creates noise, confuses agents | Only generate for detected editors |
| One giant reference file | Defeats the purpose of extraction | Split by concern (standards, arch, testing) |
| No inline summary after extraction | Agent can't decide if it needs the reference | Always keep 1-2 line summary |
