Skip to content

Commit 12f63a4

Browse files
gatesngatesn
authored
Add AGENTS.md and some basic skills (#7484)
The skills are cribbed from the Velox repository and updated for Vortex. Also permits renovate bot to self-approve PRs. --------- Signed-off-by: Nicholas Gates <nick@nickgates.com>
1 parent 01679cd commit 12f63a4

File tree

8 files changed

+402
-80
lines changed

8 files changed

+402
-80
lines changed

‎.agents/skills/ci-failure-analysis/SKILL.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
name: ci-failure-analysis
3+
description: Analyze Vortex GitHub Actions CI failures. Use when asked to investigate failed CI runs, failed jobs, or when the user mentions "/ci-failure-analysis".
4+
---
5+
6+
# Vortex CI Failure Analysis Skill
7+
8+
Analyze failed GitHub Actions runs for the Vortex repository and identify whether the failure is
9+
caused by the PR, pre-existing flakiness, infrastructure, or an unrelated main-branch issue.
10+
11+
## Inputs
12+
13+
Use any PR number, repository, run ID, failed job metadata, or log snippets supplied by the user or
14+
automation prompt. If a needed value is missing, discover it with the narrowest `gh` command that
15+
can answer the question.
16+
17+
## Workflow
18+
19+
1. List failed jobs for the workflow run:
20+
21+
```bash
22+
gh run view <run-id> --repo <owner/repo> --json jobs
23+
```
24+
25+
2. Fetch only failed job logs first:
26+
27+
```bash
28+
gh run view <run-id> --repo <owner/repo> --job <job-id> --log-failed
29+
```
30+
31+
If that fails, use the Actions API:
32+
33+
```bash
34+
gh api repos/<owner/repo>/actions/jobs/<job-id>/logs
35+
```
36+
37+
3. If any `gh` command fails with `error connecting to api.github.com` in a sandbox, rerun it with
38+
escalated network permissions immediately.
39+
40+
4. Classify each failure:
41+
42+
- Rust build errors: compiler diagnostics, spans, trait bound failures, feature-gate issues.
43+
- Rust test failures: failing test name, panic/assertion output, expected vs actual values,
44+
source path and line.
45+
- Clippy failures: lint name, file path, line, and suggested fix if shown.
46+
- Formatting or public API failures: changed files and commands needed to regenerate output.
47+
- Python/docs failures: pytest, maturin, Sphinx, doctest, or packaging output.
48+
- Infrastructure failures: toolchain download, cache, runner, network, disk, timeout, or
49+
service issues.
50+
51+
5. Fetch the PR diff and metadata only after the failing log section is understood:
52+
53+
```bash
54+
gh pr view <pr-number> --repo <owner/repo> --json title,body,baseRefName,headRefName,files,commits
55+
gh pr diff <pr-number> --repo <owner/repo>
56+
```
57+
58+
6. Reproduce narrowly when practical:
59+
60+
```bash
61+
cargo test -p <crate-name> <test-name>
62+
cargo clippy -p <crate-name> --all-targets --all-features
63+
make -C docs doctest
64+
uv run --all-packages pytest <path>
65+
```
66+
67+
7. Check whether the same failure appears on recent main-branch runs or open issues before calling
68+
it PR-caused.
69+
70+
## Report Format
71+
72+
Post or return one concise Markdown report:
73+
74+
````markdown
75+
## CI Failure Analysis
76+
77+
### Status
78+
<PR-caused | likely pre-existing | infrastructure | inconclusive>
79+
80+
### Failed Jobs
81+
- `<job name>`: <build | test | clippy | fmt | docs | infra>
82+
83+
### Relevant Log Output
84+
```text
85+
<only the failing lines needed to understand the issue>
86+
```
87+
88+
### Correlation With PR Changes
89+
<Explain whether the diff touches the failing area and cite files/functions.>
90+
91+
### Recommended Next Step
92+
<One or two concrete commands or code fixes.>
93+
````
94+
95+
## Rules
96+
97+
- Show relevant failure excerpts, not full logs.
98+
- If many tests fail, detail the first few distinct failures and summarize the rest.
99+
- Do not guess. If causation is unclear, say what was checked and what would resolve it.
100+
- Prefer one PR comment or one final report over multiple fragmented updates.

‎.agents/skills/pr-review/SKILL.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
name: pr-review
3+
description: Review Vortex pull requests for correctness, Rust soundness, performance, API compatibility, and test coverage. Use when reviewing PRs, reviewing code changes, or when the user mentions "/pr-review".
4+
---
5+
6+
# Vortex PR Review Skill
7+
8+
Review Vortex changes for issues that CI may miss: semantic correctness, Rust soundness,
9+
zero-copy and alignment invariants, performance, API compatibility, and missing regression
10+
coverage.
11+
12+
## Usage Modes
13+
14+
### GitHub Actions Mode
15+
16+
When invoked by a PR automation, the prompt may already include PR metadata, issue body,
17+
comments, and changed files. In this mode, use git commands for the diff and history:
18+
19+
```bash
20+
git diff origin/<base-branch>...HEAD
21+
git diff --stat origin/<base-branch>...HEAD
22+
git log origin/<base-branch>..HEAD --oneline
23+
```
24+
25+
If the base ref is missing, fetch only that ref:
26+
27+
```bash
28+
git fetch origin <base-branch> --depth=1
29+
```
30+
31+
Do not refetch data already provided in the prompt. Use the supplied comments and metadata as
32+
review context.
33+
34+
### Local CLI Mode
35+
36+
When the user provides a PR number or URL, use `gh` to fetch the PR metadata, comments, and diff:
37+
38+
```bash
39+
gh pr view <PR_NUMBER> --json title,body,author,baseRefName,headRefName,files,additions,deletions,commits
40+
gh pr view <PR_NUMBER> --json comments,reviews
41+
gh pr diff <PR_NUMBER>
42+
```
43+
44+
If `gh` cannot connect to `api.github.com` because of sandbox networking, rerun with escalated
45+
network permissions.
46+
47+
## Review Workflow
48+
49+
1. Read `AGENTS.md` and any nested `AGENTS.md` for project conventions.
50+
2. Identify the change intent from the PR title, body, commits, and tests.
51+
3. Group changed files by area: arrays, encodings, buffers, file/layout, integrations, bindings,
52+
docs, or CI.
53+
4. Trace changed behavior through callers, trait implementations, dtype/nullability handling,
54+
validity masks, and tests.
55+
5. Focus findings on actionable defects. Avoid commenting on formatting or issues already covered
56+
by clippy, rustfmt, or generated API checks.
57+
6. Scope verification to the change. Rust/API changes need Rust checks; docs-only, agent-only,
58+
symlink-only, and metadata-only changes should use targeted validation such as Markdown review,
59+
`ls`, `find`, `git status`, or relevant config linters.
60+
61+
## Review Areas
62+
63+
| Area | Focus |
64+
| --- | --- |
65+
| Correctness | Length and dtype invariants, nullability, validity masks, offset math, canonicalization, boundary conditions, empty arrays, scalar vs array behavior |
66+
| Rust soundness | `unsafe` blocks, aliasing, lifetimes, alignment, FFI boundaries, panic safety, ownership of buffers and arrays |
67+
| Compression and IO | Encoding metadata, statistics, layout evolution, file compatibility, scan projection/filter behavior, async IO edge cases |
68+
| Performance | Unnecessary copies, lost zero-copy behavior, avoidable allocations, poor cache locality, quadratic loops, excessive dynamic dispatch in hot paths |
69+
| Error handling | Correct `vortex_err!` and `vortex_bail!` usage, useful messages, no accidental panics on user data |
70+
| API compatibility | Public API docs, public-api lock updates, feature flags, crate boundaries, Python/Java binding impacts |
71+
| Tests | Regression coverage, edge cases, parameterized cases with `rstest`, use of `assert_arrays_eq!`, docs doctests when docs change |
72+
| Verification scope | Avoid requesting or running expensive workspace checks when the PR only changes docs, agent files, symlinks, or metadata |
73+
74+
## Output
75+
76+
Lead with findings, ordered by severity. For each finding include:
77+
78+
- File and line reference.
79+
- Why the issue is a real bug or material risk.
80+
- A concrete fix or verification path when possible.
81+
82+
Use inline review comments when the environment supports them and a precise changed line is the
83+
best place for the feedback. Keep broad design feedback in the summary.
84+
85+
If no issues are found, say so explicitly and mention any residual risk or tests not run.
86+
87+
## Principles
88+
89+
- Review the code that changed, but inspect enough surrounding code to validate invariants.
90+
- Do not infer causation from commit messages alone. Verify with code, tests, or logs.
91+
- Do not ask for broad rewrites when a narrow fix would address the risk.
92+
- Do not downgrade a correctness or soundness issue to a nit because it is inconvenient.
93+
- Be specific and proportionate.

‎.agents/skills/query/SKILL.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: query
3+
description: Answer questions about the Vortex codebase or pull requests. Use when asked a question via "/query" or when the user wants to understand code, architecture, behavior, or implementation details.
4+
---
5+
6+
# Vortex Query Skill
7+
8+
Answer questions about the Vortex project, its pull requests, and its implementation.
9+
10+
## Key Context
11+
12+
- Vortex is a Rust workspace for columnar arrays, compression encodings, file IO, and scan
13+
integrations.
14+
- `vortex-array` defines the core array traits, dtype system, canonical arrays, and base
15+
encodings.
16+
- `vortex-buffer` owns aligned zero-copy buffers.
17+
- `vortex-file` and `vortex-layout` implement file and layout reading.
18+
- `encodings/*` contains specialized compressed encodings.
19+
- Python, Java, DuckDB, and DataFusion integrations live in their own workspace areas.
20+
21+
## Workflow
22+
23+
1. Read `AGENTS.md` and any closer scoped `AGENTS.md` before relying on conventions.
24+
2. Use `rg` and targeted file reads to identify the relevant crate, module, and tests.
25+
3. If the question is about a PR, inspect the diff and comments before answering.
26+
4. If the question is about behavior, trace the implementation through public entry points,
27+
encoding-specific implementations, and tests.
28+
5. Answer with concrete file paths and line numbers when they help.
29+
30+
## Answering Guidelines
31+
32+
- Separate confirmed facts from inference.
33+
- Prefer precise code references over broad descriptions.
34+
- Mention important uncertainty and describe what would verify it.
35+
- Do not invent architecture. If the repository does not answer the question, say what you
36+
checked and what is still missing.

‎.claude‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.agents

‎.github/workflows/approvals.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,12 @@ jobs:
3333
const authorType = pr.user.type; // 'Bot' vs 'User'
3434
const authorLogin = pr.user.login; // e.g. 'github-actions[bot]'
3535
const isBot = authorType === 'Bot' || authorLogin.endsWith('[bot]');
36+
const oneApprovalBotAuthors = new Set(['renovate[bot]']);
3637
37-
const required = isBot ? 2 : 1;
38+
const required = isBot && !oneApprovalBotAuthors.has(authorLogin) ? 2 : 1;
3839
3940
console.log(`PR author: ${authorLogin} (${authorType}), isBot: ${isBot}`);
41+
console.log(`One-approval bot allowlist: ${oneApprovalBotAuthors.has(authorLogin)}`);
4042
console.log(`Approvals: ${approvalCount} / ${required} required`);
4143
4244
if (approvalCount < required) {

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,8 @@ compile_commands.json
223223
/justfile
224224

225225
# AI Agents
226-
.claude
226+
.agents/settings.local.json
227+
.claude/settings.local.json
227228
.opencode
228229

229230
# cargo sweep output

0 commit comments

Comments
 (0)