# Contributor instructions

Before substantive work, read [product scope](docs/product.md),
[architecture](docs/architecture.md), [data policy](docs/data-policy.md), and
[roadmap](docs/roadmap.md). This file is the authoritative agent entry point.

## Binding decisions

- Gizmoduck is the clean successor to Robopato.
- Use Python, Django, PostgreSQL, migrations from the beginning, Docker Compose
  for local infrastructure, and pytest for automated tests.
- Import bank accounts from CSV and Banco do Brasil/Ourocard credit cards from
  TXT. OFX is not supported.
- Keep parsing, normalization, validation, duplicate detection, preview, and
  persistence separate.
- Obtain owner approval before changing these constraints or product scope.

## Working rules

- Preserve user changes and avoid unrelated edits.
- Make small, cohesive changes with verification appropriate to their risk.
- After each implementation, start the local app and verify its health endpoint before reporting completion.
- Use isolated Git worktrees for concurrent implementation that could overlap.
- Design and plan substantial subsystems before implementing them.
- Report assumptions, checks performed, and unresolved risks accurately.
- Do not perform destructive operations, pushes, merges, releases, or history
  rewrites without explicit authorization.
- Focused local commits are allowed after verification. Inspect both staged
  paths and staged content for real financial data and secrets before every
  commit. When uncertain whether data is safe, stop and ask the owner.
- Agent-authored commits use repository-local `Codex <codex@localhost>`;
  human-authored commits retain the human contributor's identity.

## Financial data

Agents may read every file in Robopato and copy real documents for local
development, parser validation, migration, and compatibility testing. Store
real data only in ignored local directories or local databases. Never commit
raw data, identifying excerpts, snapshots, logs, screenshots, reports, or dumps.
Committed fixtures must be synthetic or irreversibly sanitized. Follow the
[full data policy](docs/data-policy.md) before handling source documents.

# Superpowers productivity policy

Use Superpowers with proportional rigor.

Optimize for correctness per unit of engineering effort, not maximum process.

## Risk scaling

Default to the lightest process that provides reasonable confidence.

For ordinary low-risk work:
- use targeted repository exploration;
- treat the task as bounded unless architecture genuinely changes;
- use a short in-chat design;
- implement inline rather than with subagents;
- target 1-3 focused new tests;
- run targeted verification during development;
- self-review the final diff;
- avoid separate review agents unless warranted.

Increase rigor for changes involving:
- security or authorization;
- destructive operations;
- financial calculations;
- concurrency;
- persistence/data integrity;
- public interfaces;
- broad architectural changes;
- historically fragile components.

## Scope

Follow YAGNI aggressively.
Do not add speculative features, tests, abstractions, refactors, or cleanup.

## Context

Explore on demand. Start with directly relevant files, callers, and tests.
Expand only when evidence indicates that more context is required.

## Tasks

Prefer cohesive behavioral tasks over tiny procedural tasks.
Batch small mechanically similar edits.
Do not create separate tasks for routine test/run/commit operations.

## Tests

Tests provide confidence proportional to risk, not maximum coverage.
For ordinary changes, target no more than 1-3 new tests.
One sufficient regression test is better than several speculative tests.

## Verification

Use narrow verification while iterating.
Run broader verification once at completion when appropriate.
Do not repeatedly execute expensive full-suite verification without a
specific reason.

## Reviews

Scale reviews to the size and risk of the diff.
Avoid redundant implementer review + task review + final review for small
changes.

## Agents and models

Do not use subagents when the current agent can comfortably complete the task.
Use cheaper models for mechanical work and stronger models for judgment,
debugging, architecture, and genuinely difficult reviews.

## Communication

Keep process narration minimal.
Surface decisions, discoveries, failures, scope changes, and verification
results rather than routine operations.