Control Instructions with Push and Pull, and Prevent Documentation Rot

Agent context should be deliberately managed. Some information must always be present; other information should be available only when the agent needs it. The same discipline applies to planning documents: active artifacts should reflect current work, while completed or stale artifacts should not silently influence future agents.

There are two ways to supply guidance:

• Push: place an instruction in persistent project or system context so that every relevant

session receives it automatically.

• Pull: make a skill or reference available so that the agent can load it when the task

requires it.

Push is appropriate when omission would invalidate the activity. Pull is appropriate when the information is optional, specialized, or costly to include in every session.

Coding standards illustrate the difference. During implementation, standards can be available as pull-based skills. The implementer can retrieve the guidance when it needs to answer a question about style or architecture without filling every context with the full standard.

During automated review, the standards should be pushed. The reviewer must compare the submitted code against them, so the rules are part of the review task rather than optional background.

This approach also supports ownership of the planning stack. Small skills can be inspected, tuned, and replaced. If an interviewing skill asks too many questions, change it. If the PRD-to-issues skill produces horizontal tasks, strengthen the vertical-slice rule. Observability and control are more valuable than dependence on a large opaque framework that the team cannot debug.

Documentation requires similar control. A completed product requirements document may be accurate on the day it is written but become misleading after implementation, refactoring, user feedback, and renamed modules. An agent that discovers the old document may treat it as current truth even when the code has moved on. This is documentation rot.

One response is to remove completed planning documents from the active repository or mark their issues closed. A closed issue remains retrievable but visibly signals that it is historical. Negative decisions and out-of-scope items should be preserved during active work because they define completion, but they should not remain indefinitely as unqualified current instructions.

Every pushed token consumes context and competes with the task. Persistent instructions that are rarely relevant make all sessions worse. At the same time, important standards that are merely available but never loaded can fail to influence the work.

Stale documentation creates a different failure: the agent receives confident but outdated context. Because the document appears authoritative, it can steer exploration and implementation away from the current code.

Create an instruction map for the workflow:

1. Keep the base system and project prompt minimal.
2. Push only rules that must apply in every relevant session.
3. Store specialized workflows as small pull-based skills.
4. During implementation, let the agent pull architecture and coding guidance as needed.
5. During review, push the standards that define acceptance.
6. Monitor which skills the agent uses and tune them when recurring failures appear.
7. Close, archive, or remove completed PRDs and issue documents from active context.
8. Preserve historical artifacts only with a visible status that prevents them from

appearing current.

Apply inversion of control to the agent stack. The team should understand how planning, issue generation, implementation, review, and merge prompts work. A workflow that can be inspected is easier to repair when behavior changes.

Pull-based guidance can be missed. The agent may not recognize that a skill is relevant. Critical standards therefore need to be pushed during activities where compliance is mandatory.

Removing completed documents reduces the chance of stale influence but also makes historical intent less immediately visible. Closing rather than deleting can preserve access while signaling that the artifact is no longer active.

There is no single universal retention rule. The controlling principle is that an agent should not encounter old planning material without a clear indication of its status.

Push only what must always be present, let agents pull specialized guidance, and keep the instruction stack small and inspectable. Treat stale planning documents as hazardous context, not harmless history.