Skip to content

feat: add develop-with-evidence and doris-pr-description skills - #16

Merged
morningman merged 3 commits into
apache:mainfrom
morningman:add-develop-with-evidence-and-pr-description-skills
Nov 4, 2026
Merged

feat: add develop-with-evidence and doris-pr-description skills#16
morningman merged 3 commits into
apache:mainfrom
morningman:add-develop-with-evidence-and-pr-description-skills

Conversation

@morningman

@morningman morningman commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

Adds two contributor-side skills for the part of a Doris change that comes before review: writing it, and then opening its PR. A handoff file connects them, so the PR description is written from the evidence gathered during development instead of being reconstructed from the diff afterward. doris-repo-review already covers the review itself.

Three commits: one per skill, and the docs that the two new skills made out of date. doris-pr-description comes first because develop-with-evidence points into its files.

1. feat: add doris-pr-description skill

skills/doris-pr-description writes, rewrites, or checks the title and description of an apache/doris PR against a PR standard built around what a reviewer needs in the first minute: a Background for readers who don't know the module, a Problem Summary that explains the size of the diff, and the answers only the author can give (why this approach, what was tested, what changes for existing users).

Path Purpose
SKILL.md Four modes (Create, Update, Rewrite, Check) and the workflow: collect facts → classify → stop and ask → write → check → show and publish
references/types/, references/examples/ 10 PR types, each with what reviewers check, its required Details fields, and a complete worked example
references/handoff-intake.md, references/development.md The two ends of the handoff with develop-with-evidence: what the PR step takes as given, and what development must establish
references/facts/ Collecting facts without a handoff file: the diff, existing tests and CI coverage, where a bug came from and which release branches have it, submodule pointers
scripts/check_pr.py Structural checker: title format, PR type, sections, required fields, the Change map of a large diff, the Check List, the Feature issue rule, leftover placeholders, length. --self-test checks every example and type file
scripts/diff_profile.py Where a diff's lines go (production code, tests, generated output, docs, submodule pointers), overall and per commit

GitHub writes (git push, gh pr create / gh pr edit, and gh issue create for a Feature without an issue) happen only after the user confirms the drafts, or when the request itself said to publish without review. Rewrite and Check modes never write to GitHub.

2. feat: add develop-with-evidence skill

skills/develop-with-evidence is a six-stage development workflow. Its aim is that every claim in the final PR rests on evidence that matches the final code.

Stage What it establishes
1. Scope For a bug, that the defect is real (reproduced on the baseline, or traced through a causal chain) before any code changes, and a stop-and-ask when it is disproved or can't be judged; the contract, the acceptance results, the PR type, and a verification plan sized to the change
2. Implement The causal chain or the target contract, the related paths, and the reason for every non-obvious edit
3. Verify Tests that tell right from wrong: they fail on the baseline and pass on the candidate, show no false passes (zero cases, everything skipped, mocks hiding the logic), and will actually run in CI
4. Self-review One purposeful pass over the current diff, always called a self-review, never an independent review
5. Evidence Evidence bound to the final candidate: re-verification after later edits, commits, or rebases; stale results become NOT_RUN
6. Deliver A Ready / Partially verified: <gap> / Not ready: <reason> pre-submission status and a summary for the developer

Verification is chosen by change type (references/change-types/: bugfix, feature, enhancement, refactor, performance, test/CI, config/build/migration, frontend and low-impact, revert). Reading-heavy evidence work, such as long logs, caller tracing, and cross-branch checks, can go to subagents; every judgment and code change stays with the main agent.

The skill leaves an English handoff file at $(git rev-parse --git-common-dir)/pr-handoff/<branch>.md, inside .git so that it is never committed. It holds a PR description draft in the repository's template, the decisions and their alternatives, the parts of the change, the existing tests, the evidence entries, and the AI involvement. The skill never pushes or opens a PR.

3. docs: add develop-with-evidence and doris-pr-description to the README

  • Adds both skills to the "Working on Doris itself" table, with a short paragraph on how the three contributor-side skills follow a change and on the handoff file that connects the first two. Also adds two "You say / What loads" rows, the per-skill dependencies, the checker self-test under Verification, and the layout tree entries.
  • Rewrites the paragraph that said nothing here builds Doris or runs tests and that the only GitHub write was the PASS comment, since neither is true any longer. It now says which skill edits code, builds, and runs tests (develop-with-evidence), which stays read-only (doris-repo-review), and where GitHub writes come from.
  • CLI-CONTRACT.md: names all three contributor-side skills as outside the doriscli contract.

Notes for reviewers

  • Both skills are in English, like the rest of the repository's skills (docs: translate remaining Chinese content to English in doris-debug skills #5). develop-with-evidence was drafted in Chinese and is translated here one to one: same rules, structure, and file layout. A side-by-side review of the translation against the Chinese original found no omitted rules; its wording fixes are folded in. doris-pr-description was already English apart from the Chinese trigger phrases in its description; those are now English examples, with a note that requests in any language count. The repository's own triggering test (verify/behavior/triggering.sh) already routes Chinese prompts to skills whose descriptions are English only.
  • check_pr.py and diff_profile.py are marked executable, like every other script under skills/.
  • No verify/ changes: neither skill makes a DDL or doriscli claim for L1/L2 to check, and doris-pr-description carries its own self-test.

Testing

  • python3 skills/doris-pr-description/scripts/check_pr.py --self-test → Self-test: 11 examples in 10 files, 0 problems.
  • python3 skills/doris-pr-description/scripts/diff_profile.py HEAD~3..HEAD runs on this repository and prints the per-kind and per-commit split.
  • No CJK characters remain under either skill directory. Every relative link in develop-with-evidence/SKILL.md and README.md resolves, agents/openai.yaml parses, and both description fields are under the 1024-character limit (920 for doris-pr-description, 743 for develop-with-evidence).
  • The four source links in develop-with-evidence/references/sources.md return HTTP 200.

🤖 Generated with Claude Code

morningman and others added 3 commits November 4, 2026 14:48
morningman @claude
feat: add doris-pr-description skill
72a7383 
Writes, rewrites, or checks the title and description of an apache/doris
PR against the Doris PR standard: four modes (Create, Update, Rewrite,
Check), ten PR types with their required fields and worked examples, a
structural checker (check_pr.py, with --self-test) and a diff profiler
(diff_profile.py). Takes its facts from the handoff file that
develop-with-evidence leaves when there is one, and writes to GitHub
only after the user confirms the drafts.

The trigger phrases in the description are English examples, with a
note that requests in any language count, like the repository's other
skill descriptions.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
morningman @claude
feat: add develop-with-evidence skill
06ab5c3 
A six-stage development workflow (scope, implement, verify,
self-review, evidence, deliver) that ties every claim in the final PR
to evidence matching the final code: it confirms that a reported bug is
real before fixing it, chooses verification by change type, checks that
tests fail on the baseline and pass on the candidate, re-verifies after
later edits or rebases, and ends with a Ready / Partially verified /
Not ready pre-submission status.

It leaves an English handoff file under
$(git rev-parse --git-common-dir)/pr-handoff/ with a PR description
draft and the facts behind it, which doris-pr-description takes as
given. The skill never publishes a PR.

The skill was drafted in Chinese; this is its English translation, with
the same rules, structure, and file layout.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
morningman @claude
docs: add develop-with-evidence and doris-pr-description to the README
a373ea8 
List both skills under "Working on Doris itself", explain how the three
contributor-side skills follow a change and the handoff file between
the first two, and add their routing examples, dependencies, the
checker self-test, and layout entries.

The paragraph that said nothing here builds Doris or runs tests, and
that the only GitHub write is the PASS comment, no longer held: it now
names the skill that edits code and runs tests, the one that stays
read-only, and both sources of GitHub writes. CLI-CONTRACT.md names all
three contributor-side skills as outside the doriscli contract.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@morningman
morningman merged commit 0b36dcb into apache:main Nov 4, 2026
This was referenced Nov 10, 2026
Open
Merged
hello-stephen pushed a commit to apache/doris that referenced this pull request Nov 14, 2026
@morningman
[chore](build) Update doris-skills submodule with four new skills (#7…
42b148b 
…0582)

### Background

`doris-skills` is a submodule that points at apache/doris-skills, the
Apache Doris repository of agent skills: instructions and scripts that
coding agents such as Claude Code and Codex load for Doris tasks.
Nothing builds from it; it is checked out on request (`git submodule
update --init doris-skills`) and by the CI jobs that clone every
submodule. This repository pins `c0aca2f` (apache/doris-skills#2, June),
which has three skills.

### What problem does this PR solve?

Issue Number: None
Related PR: #64240 (the previous update of this pointer), #70422 (moves
the same pointer to `0b36dcb` and adds the `AGENTS.md` guidance;
conflicts with this PR on that line), apache/doris-skills#17 (the commit
this PR pins)
PR Type: Build/CI/Chore

Problem Summary:

Since `c0aca2f`, doris-skills has merged 13 PRs that add four skills,
for debugging, local PR review, development, and PR descriptions, and a
checkout of this repository still gets none of them. This PR moves the
pointer to `c353d71`, the tip of doris-skills `main`, and changes
nothing else. Builds, tests, and Doris users see no change.

| | Skills in `doris-skills/skills/` |
|---|---|
| master (`c0aca2f`) | `doris-architecture-advisor`,
`doris-best-practices`, `doris-profile-reader` |
| this PR (`c353d71`) | `develop-with-evidence`,
`doris-architecture-advisor`, `doris-best-practices`, `doris-debug`,
`doris-pr-description`, `doris-profile-reader`, `doris-repo-review` |

### Details

- **Affected:** Only the `doris-skills` pointer. The CI jobs that clone
every submodule (`submodules: recursive` in `be-ut-mac.yml`,
`build-extension.yml`, `build-thirdparty.yml`, `build-ui.yml`, and
`checkstyle.yaml`, and `git submodule update --init --recursive --depth
1` in the performance pipeline's `compile.sh`) clone doris-skills at
`c353d71` without reading it; `build.sh` and `run-be-ut.sh` update only
the `contrib/` submodules they name.
- **Developer and release impact:** Developers who check out the
submodule get the seven skills at `c353d71`, about 2.3 MB; existing
checkouts keep their commit until the next `git submodule update`.
Release builds don't change, since no script in this repository reads
`doris-skills`.
- **License and third-party:** None. doris-skills is an Apache-2.0
repository of the ASF, and no file from it is added to this tree.
- **Rollback:** Revert this PR; local submodule checkouts made meanwhile
do no harm.

### Testing

- `git ls-remote https://github.com/apache/doris-skills refs/heads/main`
returns `c353d71bc50d6c0baf1831dec33cbfa0abc64ef2`, the commit this PR
pins: the squash merge of apache/doris-skills#17, not a PR-only commit.
`c0aca2f` is its ancestor.
- A fresh clone of the URL in `.gitmodules`, checked out at `c353d71` as
`git submodule update --init doris-skills` does, holds the seven skills
in the table above.
- `python3 skills/doris-pr-description/scripts/check_pr.py --self-test`
at `c353d71` reports `Self-test: 11 examples in 10 files, 0 problems`.

### Notes for Reviewers

- The pointer moves over 13 commits of apache/doris-skills (#3 to #17),
+10,047 −45 in 114 files, each reviewed and merged there; the three
skills pinned today don't change. In this repository's diff, only the
pin itself needs checking.
- #70422 changes the same line, to `0b36dcb` (apache/doris-skills#16).
Whichever of the two merges second keeps `c353d71`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@morningman