# Agent Legibility Guide

In VT Code, "legibility" means that information is easily parseable by both AI agents and humans. We favor mechanical structure over aesthetic prose.

## Core Rules

1. **Tables Over Prose**: Use tables for comparisons, status reports, and multi-item lists.
2. **YAML for Metadata**: Use YAML frontmatter or code blocks for structured metadata.
3. **Remediation is Mandatory**: Every error or violation report MUST include a `Remediation` instruction.
4. **Outcome First**: Lead with the result. Do not hide the "what" at the bottom of a "how" narrative.

## Examples

### 1. Status Reporting

**Bad (Prose-heavy)**:
I successfully updated the controller.rs file to handle the new variants. I also modified the tests.rs file to include the missing imports, which fixed the compilation error. Finally, I ran cargo check and it passed.

**Good (Structured Table)**:
| Component | File | Change | Outcome |
|-----------|------|--------|---------|
| Controller | `controller.rs` | Updated `SteeringMessage` handling | Refined steering logic |
| Tests | `tests.rs` | Added `TaskOutcome` import | Fixed compilation error |
| Validation | N/A | Ran `cargo check` | **PASSED** |

### 2. Error Reporting

**Bad**:
The file `src/main.rs` is too long (600 lines). Please fix it.

**Good**:
**Violation**: File `src/main.rs` exceeds 500-line invariant (602 lines).
**Remediation**: Split `src/main.rs` into focused submodules. Extract logical sections into separate files and re-export from `mod.rs`.

## Why It Matters

Structured information survives "context loss" better. If an agent picks up a task mid-way, it can scan a table 10x faster than reading through conversational history.

## Active Monitoring

Design outputs for human oversight, not just approval. Users should be able to monitor the "pulse" of the agent and interrupt only if necessary.

1. **Step-Level Visibility**: Update your plan or task tracker after every verification step, not just at the end of a phase.
2. **Intervention Hooks**: When performing a dangerous or high-risk operation, briefly explain the safety guard you have in place (e.g., "Running in Plan Mode first to audit the diff").
3. **Loop Transparency**: If you hit a repetition guard or tool stall, explain exactly what the root cause is before attempting a pivot.

**Example (Monitoring Friendly)**:

```
• [x] Update schema.rs (outcome: added UserStats table)
• [>] Run migrations (verification: checking pg_dump)
  └ Still waiting for DB lock... (30s)
```

## Grounding & Uncertainty

### 1. Environment Grounding

Before "fixing" code, report the environment state to prevent misdiagnosing infrastructure issues as logic flaws.

- **Grounding Step**: `which node`, `env | grep PORT`, `ls -la vendor/`
- **Report**: "Environment check: `sqlite3` is present, but `DB_PATH` env var points to a read-only mount."

### 2. Uncertainty Pulse

Proactively surface doubts to reduce "Deployment Overhang".

- **Pulse**: "I have 80% confidence in the regex, but 20% uncertainty if it handles nested quotes correctly. Proceeding with a test-first approach."

## Strategic Adaptation & Planning

### 1. Explicit Planning

Use `task_boundary` and `task.md` religiously. High success is correlated with systematic planning.

- **Rule**: If a task involves more than 3 files or complex logic, create/update an `implementation_plan.md` first.

### 2. Navigation Loops & Action Bias

Avoid repeatedly reading files without taking action. If you have read 5 files without a command or write call, pause and re-evaluate your strategy.

- **Rule**: Prefer "Edit-Test" loops over "Read-Read" loops.
