# QikInstructions

A curated set of AI code-generation directives that enforce performance-first engineering discipline. Drop these files into any project's `.github/` directory to nudge AI assistants toward lean, secure, machine-conscious code.

## What This Is

Modern AI code generators default to verbose, plausible, over-abstracted output. QikInstructions is a finite, portable instruction set that counteracts this by enforcing:

- **Feature respect** — existing work is never deleted, gutted, or "simplified" without explicit permission
- **Wire before create** — the first instinct must be to find existing work, not to create new modules
- **Earned bytes** — every line justifies its existence
- **Performance budgets** — startup, memory, CPU, GPU, network as gated metrics
- **Dependency minimalism** — audit before import, prefer 50 lines over 50MB
- **Security as architecture** — OWASP-aware, input validation at boundaries, least privilege
- **Built-in diagnostics** — zero-cost when idle, exportable Markdown reports
- **Smoke and trace discipline** — coverage ledgers, drift tests, boot self-checks, retention policies
- **Rendering discipline** — don't paint what nobody sees, idle = zero GPU
- **AI draft review** — mandatory checklist before accepting generated code
- **Update backlog discipline** — large change lists stay append-only, category-grouped, and cross-checkable at project end
- **Session quality monitoring** — proactive warning when behavioral signals indicate context window degradation

## File Structure

```text
.github/
  copilot-instructions.md                 ← Master directive (always active)
  instructions/
    ai-code-review.instructions.md        ← AI output review protocol
    dependency-audit.instructions.md      ← Dependency evaluation process
    design-theory.instructions.md         ← Originality-first design reasoning
    diagnostics.instructions.md           ← Built-in debugging infrastructure
    feature-respect.instructions.md       ← Do not gut existing work (always active)
    html-web-delivery.instructions.md     ← HTML construction, caching, web perf
    memory-resources.instructions.md      ← Allocation and data layout
    multi-step-request-flow.instructions.md ← Multi-step request flow control
    performance-budgets.instructions.md   ← Budget contracts and CI gating
    rendering-efficiency.instructions.md  ← GPU/UI rendering rules
    security-boundaries.instructions.md   ← OWASP mitigations, input validation
    session-quality-monitor.instructions.md ← Proactive context degradation warning (always active)
    smoke-and-trace.instructions.md       ← Coverage ledger, drift tests, boot self-check, trace export
    update-formatter.instructions.md      ← Large update backlog grouping and [✔️] tracking
    wire-before-create.instructions.md    ← Find existing work before authoring new modules
```

## How to Use

### In a VS Code + Copilot project

Copy the `.github/` directory into your project root. The `copilot-instructions.md` file activates automatically for all Copilot interactions. The `.instructions.md` files load on-demand when the AI detects relevant context (e.g., security instructions load when writing auth code).

### As a reference

Read `copilot-instructions.md` for the complete philosophy. The specialized instruction files provide deep-dive guidance for specific domains.

### Customization

Adjust the performance budgets, metric thresholds, and language preferences to match your project's constraints. The values in these files are starting points — your project's actual budgets should be tighter.

## Philosophy

> Hardware has gotten faster. Software has gotten slower. The knowledge to build lean, responsive software still exists. These instructions revive that discipline in the age of AI-assisted development.

Constraints breed creativity. A tight budget forces a better solution. Unlimited resources produce unlimited waste.
