eko24ive/pi-config/record-evidence

Record Evidence

Capture the requested software behavior or state with the smallest useful evidence set. Use ready tools autonomously; do not turn recording into an engineering project.

Authority

Recording authorizes capture and observation only. Reporting, publishing, fixing, and durable storage require explicit instructions.

Workflow

1. Understand the objective. Identify the behavior or state, requested artifact, target, success condition, known steps, and whether the state is already prepared. When asked to show how an interaction works without a format, choose a short video; use a screenshot for a static state.
2. Apply constraints. Follow current user and applicable project guidance. Use an unambiguous prepared target satisfying those constraints; ask only when several valid targets remain.
3. Check the path. If the flow is reliably derivable from explicit instructions, prepared state, or project documentation, proceed. If it requires guessing, ask or stop.
4. Resolve a direct capability. Quietly choose a ready tool using references/capture-guide.md. Do not ask the user to choose between equivalent safe tools. Before disrupting a session or recording, verify the complete chain: target access, required interaction, recorder prerequisites, start/stop, and artifact finalization.
5. Make a hard decision. If the requested artifact can be produced directly, proceed. Otherwise explain the limitation briefly and stop.
6. Interact safely. Expected, reversible actions in local/test environments may proceed. Ask before production/customer, externally visible, billable, destructive, or irreversible actions. Never blindly retry an uncertain non-idempotent product action.
7. Capture narrowly. For video, rehearse the full flow with recording off, reset to the starting state, then follow the video workflow in the guide. Keep comparisons consistently framed. Always stop an active recording after failure.
8. Validate and hand off. Confirm the artifact exists, is non-empty, represents the intended target and behavior, and meets applicable privacy guidance. Do not replace an earlier take until the new one is validated. Return an absolute path for local files, or the exact resource URI otherwise, plus what it establishes and material limitations.

Escalation boundary

Do not:

• Author scripts or automation as a capture fallback.
• Treat a project library, test dependency, or cached binary as an available recorder.
• Search dependency caches for hidden executables.
• Send or read authentication codes, inspect or reuse tokens, inject sessions, or reconstruct authentication.
• Create another authenticated context when that requires credentials or copied session state.
• Directly modify databases, caches, rate limits, queues, service internals, source, tests, or configuration to enable capture. Ordinary product interactions allowed by the workflow above are not included.
• Install or configure packages, browsers, drivers, simulators, MCP servers, or project dependencies.
• Substitute a different artifact type when the user explicitly requested screenshot, video, trace, or another format.
• Change to a strategy that crosses this boundary after failure without discussing it with the user.

A project dependency is not a capability. A direct, ready command or configured tool is.

Temporary artifacts

Prefer resource URIs or a uniquely named OS temporary directory outside the project. Do not leave generated evidence in the project unless explicitly requested; move a tool-produced local file to temporary storage after capture when safe. Mark temporary evidence as temporary; a later publishing action is responsible for transferring it before it expires. If an artifact contains sensitive data contrary to applicable guidance, do not hand it off; discard only artifacts created by this run and explain that local deletion cannot retract tool-side exposure.

Reference

• references/capture-guide.md — direct capability checks, platform capture, evidence choice, and validation.