docs: add AI Foundations skill guide (NES-1501)

README.md

@@ -14,6 +14,10 @@ Read the [docs](https://docs.core.jesusfilm.org) or find out more about us at [j
 
 The fastest and easiest way to try Core out is via using Visual Studio Code with the Remote - Containers extension. This lets you use a Docker container as a full-featured development environment. Follow our [Getting Started Tutorial](https://docs.core.jesusfilm.org/docs/getting-started/development-environment).
 
+## AI-Assisted Engineering
+
+This repo includes AI skills that automate common engineering tasks (PR review, review feedback handling, stage branch reset). See [docs/ai-foundations.md](docs/ai-foundations.md) for the full guide.
+
 ## License
 
 [Stratis Icon Set](https://www.figma.com/community/file/1177180791780461401/Stratis-UI-Icons---1000%2B-Free-Figma-icons) by [Monty Hayton](https://www.figma.com/@designproduct) is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)

docs/ai-foundations.md

@@ -0,0 +1,90 @@
+# AI Foundations
+
+AI skills that automate common engineering tasks in core. These run inside Cursor and Claude Code — no external services, no cost beyond your existing tooling.
+
+## Prerequisites
+
+- **Cursor** with Claude model access
+- **`gh` CLI** authenticated: `gh auth login` (needs `repo` scope)
+- **Devcontainer** running (for build/lint verification)
+- **Doppler** authenticated (only needed for reset-stage Slack notifications): `doppler login`
+
+## Cursor Skills
+
+Available in `.cursor/skills/`. Trigger by typing the phrase in Cursor chat or using the skill picker.
+
+| Skill                | What it does                                                                                                                                                                                                      | When to use it                                                                   | How to trigger                                                  |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| **review-pr**        | Reviews a PR for correctness, security, design, and maintainability. Auto-loads project conventions from `.claude/rules/` and `AGENTS.md` files based on changed paths. Posts findings as inline GitHub comments. | Before requesting human review, or to get a second opinion on someone else's PR. | `review PR`, `review PR #123`, `review this PR in local mode`   |
+| **handle-pr-review** | Fetches unresolved review threads, triages each as fix/challenge/skip, applies holistic fixes, resolves threads, and posts a summary comment.                                                                     | After receiving review feedback on your PR.                                      | `check review feedback`, `address PR comments`, `handle review` |
+| **reset-stage**      | Resets the stage branch from main, re-merges all PRs labelled "on stage", auto-resolves conflicts. Reports results to Slack.                                                                                      | Stage has conflicts, has drifted, or needs a clean rebuild.                      | `reset stage`, `rebuild stage`, `dry run stage`                 |
+
+### review-pr modes
+
+- **Remote** (default): analyses the PR and posts comments directly to GitHub.
+- **Local** (`mode=local`): same analysis, displayed in chat only — nothing posted.
+- **Auto** (`auto=true`): skips the confirmation step. Always posts as `COMMENT`, never auto-approves or requests changes.
+
+### handle-pr-review triage categories
+
+| Category      | When                                                          | What happens                           |
+| ------------- | ------------------------------------------------------------- | -------------------------------------- |
+| **Fix**       | Comment is correct and pragmatic                              | Code change applied, thread resolved   |
+| **Challenge** | Comment is wrong, pedantic, or would make code worse          | Respectful reply posted with reasoning |
+| **Skip**      | Marked "nit" or "optional", or already covered by another fix | Noted in summary, no action            |
+
+### reset-stage flags
+
+```bash
+./tools/scripts/reset-stage.sh           # Dry run (safe, no changes)
+./tools/scripts/reset-stage.sh --apply   # Actual reset (destructive, prompts for confirmation)
+./tools/scripts/reset-stage.sh --apply --no-slack  # Reset without Slack notification
+```
+
+## Claude Code Commands
+
+The same skills are available in Claude Code for terminal-based workflows.
+
+| Command             | Equivalent Cursor skill |
+| ------------------- | ----------------------- |
+| `/review-pr`        | review-pr               |
+| `/handle-pr-review` | handle-pr-review        |
+
+Usage: open Claude Code in the core repo and type the command. Parameters are the same as the Cursor versions.
+
+## Convention Rules
+
+`.claude/rules/` contains coding convention files that `review-pr` auto-loads based on which files a PR changes. Engineers don't need to configure anything — the rules are applied automatically.
+
+| Rule file                        | Covers                                                           |
+| -------------------------------- | ---------------------------------------------------------------- |
+| `backend/apis.md`                | GraphQL API layer, Prisma patterns, Federation, auth, logging    |
+| `backend/workers.md`             | Background job patterns                                          |
+| `backend/customizable-blocks.md` | Custom block sync guardrails                                     |
+| `frontend/apps.md`               | React application conventions                                    |
+| `frontend/watch-modern.md`       | Watch Modern app-specific rules                                  |
+| `infra/kubernetes.md`            | Kubernetes deployment conventions                                |
+| `infra/terraform.md`             | Infrastructure-as-code patterns                                  |
+| `running-jest-tests.md`          | Jest testing workflow (use `npx jest` directly, never `nx test`) |
+
+## Troubleshooting
+
+**`gh` auth scope error when posting review comments:**
+Run `gh auth login` and ensure `repo` scope is granted. The GraphQL operations for resolving threads require write access.
+
+**reset-stage skips Slack notification:**
+Doppler must be authenticated (`doppler login`) with access to the `core` project, `dev` config. The script runs without Slack — it just won't notify the channel.
+
+**review-pr on a large PR (30+ files):**
+The skill automatically prioritises: deep review for core logic and security-sensitive files, scan for tests and utilities, skim for generated files and config. If a PR exceeds 100+ substantive files, it will recommend splitting.
+
+**"No unresolved threads" from handle-pr-review:**
+The skill uses GraphQL to fetch threads with `isResolved === false`. If threads appear unresolved in the UI but the skill finds none, check that comments are actual review threads (not PR-level comments).
+
+## Going deeper
+
+Each skill's full technical specification lives in its SKILL.md file:
+
+- `.cursor/skills/review-pr/SKILL.md`
+- `.cursor/skills/handle-pr-review/SKILL.md`
+- `.cursor/skills/reset-stage/SKILL.md`