Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jaco-brink merged 3 commits into from
Apr 1, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
426dc46
docs: add AI Foundations skill guide (NES-1501)
jaco-brink Apr 1, 2026
4b0aa1d
fix: lint issues
autofix-ci[bot] Apr 1, 2026
f42a7a6
docs: clarify tooling dependencies and Claude Code command scope
jaco-brink Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand Down
90 changes: 90 additions & 0 deletions docs/ai-foundations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# AI Foundations

AI skills that automate common engineering tasks in core. They run inside Cursor and Claude Code, using tools you already have (`gh` CLI, optionally Doppler for Slack notifications).

## 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 review skills are also available as Claude Code commands 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`
Loading