# Agent instructions ## Implementation standards apply to every workflow Staged Railspike, Railspike one-shot, and Direct work use the same implementation standards. One-shot or Direct execution can skip multiple planning steps; it does not waive component reuse, scope boundaries, risk handling, or verification. Keep the selected workflow's approval and record requirements; this clarification does not require restarting Direct work as a staged cycle or enroll it in the effort study. - Before adding markup, CSS, behavior, or API payloads, inspect existing implementations and identify the canonical components/contracts to reuse or extend. Record the relevant paths and reuse decisions in the task's existing checklist or implementation record. If a new component is necessary, explain why existing ones do not fit; do not duplicate them merely because planning steps were skipped. - Define completion through the ordinary UI/CLI entry, the end-to-end result, and required failure/retry recovery. Resolve material risks before dependent implementation and keep changes within the authorized scope. - Apply the same relevant project checks in every workflow, including affected shared consumers, themes, roles, and applicable migration/deployment dependencies. For a reported user/environment failure, replay that condition or explicitly report it unverified; a pass elsewhere does not establish recovery. Record checks and limitations honestly before calling the work complete. ## Current retraction coordination Before work involving retraction, publication guards, or registration's retraction requirements, read [the 2026-10-24 handoff](docs/plans/retraction_simplification_handoff.md). The user wants immediate content deletion with a retained retraction record, followed by later history purge, and canceled the sweep diagnostics plan. The handoff records the intended simplification and its approval boundaries. ## Human-readable formats Use the project's `Key: value` plain-text format for canonical records and human-facing source, exports, and editable files. Do not introduce JSON for these purposes. See `CONTRIBUTING.md` for boundaries and migration requirements. ## UI copy Favor removing UI text over rewriting or relocating it. Rely on an intuitive, explorable interface; avoid repeating controls or explaining internals. Keep contextual help or Explain only where users need information the interface cannot communicate. Keep essential warnings and recovery actions visible. Pages must look final on first paint: decide viewer-specific UI in the client before paint so server HTML stays static, and allow post-paint updates only for real state changes (see `CONTRIBUTING.md`). Follow the UI verification guidance in `CONTRIBUTING.md`. Track cleanup and verification in `docs/plans/ui_copy_audit_checklist.md`. ## Tests During a task, run only the smoke set plus the tests for what you changed: `./v3 test --smoke FooTest Bar::testX` (bare `./v3 test` is the smoke set alone). Do not run or wait for the full suite (`./v3 fulltest` or `./v3 test --all`); the maintainer runs it periodically. Report what you ran and say the full suite was not run. See [Tests in CONTRIBUTING.md](CONTRIBUTING.md#tests). ## Todo Do not modify `todo.txt` unless the user explicitly requests an edit to that file. Record task progress and follow-up work in the relevant planning or implementation documents instead. ## Agent procedures For recurring agent tasks such as triaging site feedback, follow the matching procedure in [`docs/agents/`](docs/agents/README.md). Feedback items live in [`docs/feedback/`](docs/feedback/README.md). When someone pastes a ZenMemes thread (link, post ID or text) and asks you to build it, follow [thread to pull request](docs/agents/thread_to_pr.md). The paste authorizes a Railspike one-shot cycle carried through to an open PR and a reply in the thread. Use a staged cycle when the requester wants to review the approach or the approach needs the maintainer's choice; ask a non-technical requester only about unknowns that change what they will get. Dependency changes, production access and irreversible decisions still stop for approval. Before starting a fix or feature, search `docs/feedback/items/` for a matching item and name its ID in the plan. When a commit addresses an item, add a `Feedback: PF-...` trailer (one per item) and update the item file in the same commit: `Workflow` (`done` only with its completion checks met; `blocked` while deployment or production acceptance is pending), `Evidence`, and a dated line in `Notes:`. Triage runs catch items that were missed. Triage commits themselves carry no `Feedback:` trailers; their proposals file is the record. ## Navigation icons When adding or renaming a navigation destination, update its icon mapping in `public/assets/theme-nav-icons.css` for icon themes (currently Word97, Chicago, and Midnight). Cover both Tools launcher buttons and Tools subnavigation where applicable. Verify the icon in each affected theme before calling the UI complete; text-only theme checks do not cover this. ## Third-party code Follow the dependency approval policy in `CONTRIBUTING.md` before adding or updating external components. Formatting requests and generic plan approvals do not authorize new third-party components. This rule also applies to small changes and temporary evaluations; keep unapproved evaluation artifacts outside the repository. ## Railspike Use Railspike by default when a task would benefit from comparing approaches, staged planning, or work across sessions, unless the user opts out. Read `docs/railspike/RAILSPIKE.md` and begin the appropriate planning step; wait for each required `Approved Step N` before advancing. Small, straightforward changes can proceed directly. Honor a decline for the same task without repeated offers. This guidance does not approve implementation. Railspike is already installed as a Git subtree at `docs/railspike/`. Keep project planning artifacts in the host project's `docs/plans/`, outside the vendored tree. See `docs/reference/railspike_workflow.md` for project-specific workflow and update instructions. ## Principles and project knowledge Read `PRINCIPLES.md` before weighing options; it wins over common industry defaults. Record durable project knowledge (decisions, preferences, background) in the repository where other contributors can find it, such as `PRINCIPLES.md`, `CONTRIBUTING.md`, reference docs or plans. Do not keep it only in a tool's private memory. ## Repository guidance Follow `CONTRIBUTING.md`, including its requirements for read-model schema changes. ## Continuing Railspike effort study Every future Railspike cycle participates in the same `railspike-effort` study under protocol P2. Follow [standing enrollment and checkpoint collection](docs/plans/effort_estimation_trial.md#continuing-enrollment--2026-10-21-protocol-p2); do not ask to select each cycle again. Keep snapshots in that cycle's artifacts and index them in the host ledger. Preserve R1, stable IDs, score revisions and incomplete outcomes; deduplicate worktree copies. Existing cycles join at their next checkpoint without invented earlier scores. Collection does not approve implementation, bypass normal approvals, require debug mode or authorize uploads.