Instructionalist Docs

# Instructionalist Agent 🎩

> [!TIP]
> This agent does **not** include an XML version like others. It’s designed to be interactive and adaptive.
> The AI needs you in the mix for this one — without your input, it can’t deliver truly accurate repo instructions.

The **Instructionalist** is your repo’s detail-obsessed detective and architectural advisor, rolled into one relentless (but friendly) interrogator. It digs through your repo **and** your brain section-by-section, making sure every critical instruction is surfaced, clarified, and documented — no filler, no fluff, maximum context.

> *“Every section matters. I don’t do shortcuts. If there’s a gap, I’ll find it — if there’s a rule, I’ll catch it. Let’s make your instructions future-proof.”*

---

## What Is It? 🧩

Instructionalist is a Copilot agent (Markdown only) that walks you through creating an **outstanding** `.github/copilot-instructions.md` file for your repo.
It’s interactive, adaptive, and never generic:

- Breaks documentation into well-defined sections with clear goals
- Asks targeted questions to fill in gaps
- Encourages (but never nags for) excellence
- Updates output only when you provide better, clearer, or more complete answers
- Supports a **fun, detective persona** on request — just say “fun” at any time

---

## Why? 🦄

- **Outstanding docs save everyone’s time:** No more “what’s the rule here?” confusion.
- **Section-driven:** Uses your own embedded section metadata to cover everything from project overview to test coverage to anti-patterns.
- **Adaptive:** Switch to “fun” mode for personality, jokes, and detective-themed banter — or keep it serious for focus.
- **Safe:** Never overwrites work unless the new info is genuinely better. Flags missing content clearly, never invents, never assumes.
- **Built-in Critical Constraints:** Appends a set of must-follow repo rules unless you’ve already stated them in your own words.

---

## How It Works 🛠️

1. **Start the mode** in Copilot Chat (Markdown).
2. The AI works section-by-section, based on the in-file metadata.
3. For each section:
   - Checks if your input improves that section.
   - Asks focused questions using the section’s specific points.
   - Lets you skip sections by typing `skip` — marking them as `(TBD)` if required.
   - For optional sections, it will **ask before** adding `(TBD)` so you can decide whether to include them.
4. Only references external or internal docs if they are **necessary** and **up-to-date** — and always asks you before adding them.
5. Appends **Critical Constraints** automatically unless you’ve already included them.

---

## Critical Constraints 📦

If you haven’t already specified these in your own way, they’ll be added automatically: