REPOCHICKEN / FIELD GUIDE

Repository context
for coding agents.

What to check when coding agents ignore instructions, miss repository conventions, or lose context between sessions.

By RepoChicken. This guide explains discovery, the first stage of RepoChicken existing-project onboarding. Migration and verification require separately agreed scope and owner-approved stages. It makes no promise of improved agent performance.

What is repository context?

Repository context is the information an agent can use to interpret and change a codebase: instructions, source files, architecture decisions, setup commands, tests, and domain knowledge. The existence of a document does not establish that an agent found, loaded, or followed it.

Agent instructions: durable rules and direction

An instruction file such as AGENTS.md communicates repository-wide constraints and routes readers to deeper material. Which files apply depends on the chosen tool and configuration. Verify that environment rather than assuming a filename guarantees discovery.

Keep routing and durable rules concise. If a runtime changes, revise the relevant operational playbook and remove contradictory instructions wherever they remain.

Knowledge routes: make the next document findable

A documentation index links focused topics so a reader can find relevant detail. Useful topics include architecture boundaries, business rules, and workflow procedures. Discovery works with the documentation your team already maintains. Any later adoption of Open Knowledge Format (OKF) is proposed and approved with the owner; the audit does not require a platform change.

Troubleshooting recurring context problems

Why do coding agents ignore instructions?

Separate three questions before adding more rules:

• Present: Is the instruction in the repository snapshot being used, and does it apply to this directory and task? Check for conflicting guidance.
• Loaded: Does the chosen tool expose evidence that it read the applicable instruction? Check its configuration and any loading record. A file's presence or an agent's claim alone is not proof.
• Followed: Does the actual work satisfy a specific rule? Compare an authorized representative task with the documented requirement, such as the expected test command. Record mismatches and untested behavior.

Correct a missing route, stale command, or contradiction where you find it. Recheck the same task and setup; longer instructions alone do not establish a fix.

Why do coding agents lose context between sessions?

Keep a short task note with the decisions and their sources, unfinished work, pending approvals, and next step. Link to durable project facts instead of copying entire conversations. Before continuing in a fresh session, check that the agent can find those sources and identify what remains unresolved. A saved note is useful only when the next session can retrieve and use it; record gaps rather than assuming continuity.

Repository context audit checklist

1. Fix the scope. Record the repository commit, chosen coding-agent setup, and workflows being inspected.
2. Map the instructions. Locate entry points such as AGENTS.md and tool-specific configuration. Check which directories and tasks each instruction applies to in the agreed environment.
3. Compare guidance with code. Check setup and test commands, architecture descriptions, and conventions against the actual configuration. Do not execute commands without permission.
4. Trace missing or conflicting context. Follow documentation links, identify contradictions, and distinguish missing knowledge from instructions that are merely long.
5. Write verifiable findings. Include the source file, snapshot, consequence, confidence, recommended correction, and an acceptance check. Label untested behavior as a validation gap.
6. Agree the handoff. Prioritize changes and identify an owner. Treat implementation and repeated agent task evaluation as separately scoped work.

For example, a stale test command is a documentation defect if it disagrees with the repository configuration. Whether correcting it improves agent task completion remains a separate question requiring controlled trials.

Workflow playbooks: commands with boundaries

A playbook should state the environment, commands, expected result, and limits on what the operator may change. For a port conflict, identify the owner before deciding whether to reuse your own container or select another port.

For example, a guide that says to stop an unidentified process could put unrelated work at risk. A safer instruction would identify ownership and offer an alternate port. This is a hypothetical scenario, not an observed incident.

What makes a finding actionable?

An actionable finding names a fixed repository snapshot, exact evidence, consequence, confidence, recommendation, and acceptance check. A possible failure should be labeled a hypothesis until it is observed.

In the illustrative report, a fictional instruction file tells an agent to merge its own work once tests pass. Its proposed acceptance check is specific: a representative change shows a distinct review before merge. This example shows the format, not a completed audit or proof of results. Explore the example.

Audit, implementation, and evaluation

An audit inspects evidence and recommends changes. Implementation changes the repository. Evaluation tests resulting behavior with fixed tasks and controlled conditions. These are separate activities and should be scoped explicitly.

A before/after evaluation should hold the task, agent configuration, and environment constant where possible, repeat runs, and record failures and inconclusive outcomes. Byte counts and one successful task are not sufficient evidence of a performance gain.

From context review to project onboarding

Open Knowledge Format (OKF) organizes durable knowledge into linked project documents. Governance defines scoped agent working rules, owner approvals, and review steps; it does not itself enforce permissions. RepoChicken onboarding starts with discovery, reconciles decisions with the owner, and migrates existing projects in approved stages while preserving their code, tools, and conventions. Commands, knowledge retrieval, and task behavior would be checked where agreed, with untested behavior kept explicit and guidance for later maintenance.

The illustrative example report shows how findings, recommendations, and acceptance checks would be organized. It is not a completed audit or proof of results. Read about RepoChicken engagements or start a conversation by email.