From 9d8817646d1e0306c0c47e1859dfe23a2846c99d Mon Sep 17 00:00:00 2001
From: Illia Polosukhin <ilblackdragon@gmail.com>
Date: Tue, 10 Mar 2026 18:06:47 +0000
Subject: [PATCH] feat: add PR template with risk assessment (#837)

* feat: add PR template with risk assessment and review tracks

Add a pull request template that includes summary, change type,
validation checklist, security/database impact sections, blast radius,
and rollback plan. Update CONTRIBUTING.md with review track definitions
(A/B/C) based on change risk level.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: expand CONTRIBUTING.md with setup, workflow, and guidelines

Add getting started, development workflow, code style summary,
database change guidance, and dependency management sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 .github/pull_request_template.md | 50 ++++++++++++++++++++++++++++++++
 CONTRIBUTING.md                  | 49 +++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 .github/pull_request_template.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..4fc7cbf2
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,50 @@
+## Summary
+
+<!-- 2-5 bullet points: what changed and why -->
+
+-
+
+## Change Type
+
+<!-- Check one -->
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] CI/Infrastructure
+- [ ] Security
+- [ ] Dependencies
+
+## Linked Issue
+
+<!-- Closes #N, or "None" -->
+
+## Validation
+
+<!-- How did you verify this works? -->
+
+- [ ] `cargo fmt`
+- [ ] `cargo clippy --all --benches --tests --examples --all-features`
+- [ ] Relevant tests pass: <!-- list specific tests -->
+- [ ] Manual testing: <!-- describe what you tested -->
+
+## Security Impact
+
+<!-- Does this change affect: permissions, network calls, secrets, file access, tool execution, sandbox policy? If yes, describe. If no, write "None". -->
+
+## Database Impact
+
+<!-- Does this add/modify migrations, change schema, or affect both PostgreSQL and libSQL? If yes, describe. If no, write "None". -->
+
+## Blast Radius
+
+<!-- What subsystems does this touch? What could break? -->
+
+## Rollback Plan
+
+<!-- How to revert if this causes problems? For Track C changes, this is mandatory. -->
+
+---
+
+**Review track**: <!-- A (docs/tests/chore) | B (feature/refactor) | C (security/runtime/DB/CI) -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5c719811..1c5c6d88 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,34 @@
 # Contributing
 
+## Getting Started
+
+```bash
+git clone https://github.com/nearai/ironclaw.git
+cd ironclaw
+./scripts/dev-setup.sh
+```
+
+This installs the Rust toolchain, WASM targets, git hooks, and runs initial checks.
+
+## Development Workflow
+
+```bash
+cargo fmt                                                    # format
+cargo clippy --all --benches --tests --examples --all-features  # lint (zero warnings)
+cargo test                                                   # unit tests
+cargo test --features integration                            # + PostgreSQL tests
+```
+
+## Code Style
+
+- Zero clippy warnings policy
+- No `.unwrap()` or `.expect()` in production code (tests are fine)
+- Use `thiserror` for error types, map errors with context
+- Prefer `crate::` for cross-module imports
+- Comments for non-obvious logic only
+
+See `CLAUDE.md` for full style guidelines.
+
 ## Feature Parity Requirement
 
 When your change affects a tracked capability, update `FEATURE_PARITY.md` in the same branch.
@@ -9,3 +38,23 @@ When your change affects a tracked capability, update `FEATURE_PARITY.md` in the
 1. Review the relevant parity rows in `FEATURE_PARITY.md`.
 2. Update status/notes if behavior changed.
 3. Include the `FEATURE_PARITY.md` diff in your commit when applicable.
+
+## Review Tracks
+
+All PRs follow a risk-based review process:
+
+| Track | Scope | Requirements |
+|-------|-------|-------------|
+| **A** | Docs, tests, chore, dependency bumps | 1 approval + CI green |
+| **B** | Features, refactors, new tools/channels | 1 approval + CI green + test evidence |
+| **C** | Security (`src/safety/`, `src/secrets/`), runtime (`src/agent/`, `src/worker/`), database schema, CI workflows | 2 approvals + rollback plan documented |
+
+Select the appropriate track in the PR template based on what your changes touch.
+
+## Database Changes
+
+IronClaw uses dual-backend persistence (PostgreSQL + libSQL). All new persistence features must support both backends. See `src/db/CLAUDE.md`.
+
+## Adding Dependencies
+
+Run `cargo deny check` before adding new dependencies to verify license compatibility and check for known advisories.