docs: define development and review workflow

CONTRIBUTING.md

@@ -12,11 +12,11 @@ We welcome AI-assisted contributions — AI assistance itself is not a problem.
 
 To make sure your contribution is assessed fairly:
 
-- **Link a pre-existing issue.** Non-trivial changes should fix or implement something already reported in an issue. An issue created after the pull request is a much weaker signal than a genuine problem report.
-- **Keep the diff mapped to the issue.** Every changed area should be explainable from the linked issue. Unrelated refactors, formatting churn, or dependency bumps belong in separate pull requests with their own motivation.
+- **Link a pre-existing issue.** Product bug fixes and features require one; self-scoped maintenance does not. Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md) for scope, linkage, and revert references. If a required issue is missing, ask maintainers to open or approve one before implementing. Use maintainer-approved private tracking for security-sensitive fixes that cannot be reported publicly.
+- **Keep the diff mapped to the scope.** Every changed area should be explainable from the linked issue or stated maintenance scope. Unrelated refactors, formatting churn, or dependency bumps belong in separate pull requests with their own motivation.
 - **Describe the problem in your own words.** A short statement of what breaks or what is needed, and why this approach fixes it, is worth more than a long generated report.
 - **Validate against the reported behavior.** Show how the reported problem was reproduced and confirmed fixed. Generic checklists and raw tool output are not verification.
-- **Do not pad with tests or defensive code.** New tests are not expected by default. Add them only when the linked issue calls for them, keep them minimal, and explain in the pull request why each is necessary; speculative error handling and coverage of hypothetical failure modes inflate the diff without adding value.
+- **Do not pad with tests or defensive code.** New tests are not expected by default. Add a minimal test when the issue or task requires it, it reproduces the reported regression, or it guards behavior whose breakage would otherwise go unnoticed. Explain why it is needed; speculative error handling and coverage of hypothetical failure modes inflate the diff without adding value.
 - **Disclose AI automation.** If an AI agent produced or co-produced the change, end the pull request body with the model and effort level (for example, `Assisted by: GPT-5.6 High`; effort is optional when your tool does not report it). The PR template intentionally omits this footer; agents add it themselves. Disclosure is transparency only — it does not affect how the change is assessed.
 
 If your pull request receives an `ai-slop` label, the fastest way to clear it is substantive: link (or ask us to create) the underlying issue, narrow the scope, or push implementation changes that respond to review feedback. Editing the pull request description alone does not change the assessment.
@@ -127,8 +127,59 @@ pnpm portable
 
 ## Contributing Your Changes
 
+### Development Workflow
+
+Scale the work to the change. A wording fix needs a focused diff check; a change
+to configuration persistence, asynchronous state, or system networking needs
+evidence for the affected behavior.
+
+1. **Define the outcome.** Identify the triggering action, relevant platform and
+   configuration, and actual versus expected behavior. For a bug fix, separate
+   the reported symptom from the suspected cause. State what remains unknown.
+2. **Trace the affected path.** Read the relevant callers, state owners, and
+   failure paths before editing. Follow the module rules in
+   [src/AGENTS.md](src/AGENTS.md) or [src-tauri/AGENTS.md](src-tauri/AGENTS.md)
+   where applicable. Choose a reproduction or observable check that can
+   distinguish the old behavior from the intended result.
+3. **Make the smallest complete change.** Address the confirmed cause and its
+   affected instances within scope. Keep unrelated cleanup separate. Add a test
+   only when justified by the contribution expectations above.
+4. **Verify the result.** Use the checks below that cover the changed behavior.
+   If reproduction is unavailable, explain the alternative evidence and its
+   limits rather than claiming the reported problem is confirmed fixed.
+5. **Review and resolve findings.** Follow [REVIEW.md](REVIEW.md). For changes
+   altering concurrency, persistence, system networking, or shared-contract behavior,
+   seek an independent review with fresh context. Check each finding against
+   the code before changing it; return fixes to the implementer when working
+   with a separate reviewer.
+
+### Choosing Validation
+
+Use existing checks appropriate to the affected paths; this is not a requirement
+to run every command for every change. Run commands from the repository root.
+
+| Changed behavior | Relevant checks and evidence |
+| --- | --- |
+| Frontend logic or state | `pnpm lint`, `pnpm typecheck`, and existing focused tests via `pnpm test <path>`; exercise the affected user interaction. |
+| Rust logic | `cargo clippy-all`, relevant Cargo tests, and the affected failure or recovery path. Platform-specific branches require checks on those platforms. |
+| IPC or event contracts | `pnpm gen:contract --check`, frontend type checking, and inspection of both producers and consumers. |
+| UI or native integration | Exercise the changed flow; use a screenshot for visual changes and the native app for window, Service/Core, DNS, or system-proxy behavior. |
+| Documentation | Check wording, relative links, referenced commands, and consistency with the authoritative rule or implementation. |
+
+Tie results to the code reviewed: identify the base/head commits for branch
+comparisons and include task-relevant staged, unstaged, and untracked files in a
+local review. Report
+the command or interaction, observed result, and material gaps in the existing
+conversation or PR; no separate verification report is required. Static checks,
+mocks, browser previews, native runs, and remote CI establish different things.
+When code changes after verification, repeat affected checks. Attribute a failure
+to the baseline only after comparing the same check on the base revision.
+
 ### Before Committing
 
+Run the applicable checks from the validation guidance above. After formatting
+or generation, inspect the final diff and stage only the intended changes.
+
 **Code quality checks:**
 
 ```bash