ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2026-06-03 16:56:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

regen skills

Browse Source
This commit is contained in:
Denis Angell
2026-05-13 20:57:25 +02:00
parent 196707b242
commit 17a22a33ab
14 changed files with 1215 additions and 483 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
.github/scripts/doc-agent/prompts/document-file.md vendored
View File

@@ -65,22 +65,219 @@ classes, and gotchas:
## Process
1. If "Authoritative AI Context" is provided in the user prompt, treat it as
the source of truth for the file's intent and behavior. Your task is to
translate that prose into structured Doxygen comments on the declarations.
2. Read the target file completely
3. Read the corresponding skill file in `docs/skills/` if one applies
4. Identify entities that need documentation (public classes, structs,
public methods, free functions in headers, enums)
5. For each entity: cross-reference the ai.md context, read the implementation
(and tests if helpful), then write a Doxygen comment that captures behavior
and intent
6. Use the Edit tool to add the comments to the file
7. Do NOT modify code logic — only add documentation
8. Do NOT add documentation to entities that don't need it (private members
with obvious purpose, simple getters where the name is self-explanatory)
9. Do NOT read the `.ai.md` file yourself — it is already injected into your
prompt when one exists for the target file
Documenting a declaration is not the same as "writing a doxygen comment
above it". It is producing the **total** set of comments that should
surround the declaration after this pass — which includes the docstring
and any inline comments that remain inside the function body or next to
a data-literal initializer. Existing comments in the file are inputs,
not outputs you are preserving.
For each entity (class, struct, public method, free function in a header,
enum, public field):
1. **Read** the declaration, its full implementation, and **every comment
that is currently attached to it** — the Doxygen above it, any `//!`
line, any inline `// ...` annotations next to its initializer or
inside its body. Treat all of these as raw information about intent.
2. **Cross-reference** the ai.md context (already injected in your
prompt) and the module skill file. Also grep for the entity's name
to find callers and tests where the behavioral contract is exercised
— those are often the best source of what to write.
3. **Decide what the reader needs**, in this order:
a. A docstring that captures behavior, contract, invariants, and the
WHY. This is the primary deliverable.
b. Inline comments **only** where they document something the
docstring cannot reasonably hold — typically a non-obvious local
invariant, a workaround for a specific bug, a tricky branch whose
WHY is genuinely local. If the inline comment just narrates what
the next line does, it does not belong.
4. **Produce a single edit** that replaces the entity's full comment
surface with the result of step 3. Concretely:
- If you wrote a docstring whose contents subsume an existing `//!`
or section-header prose comment, **remove** the old comment as part
of the same edit. Do not leave both.
- If you wrote a docstring whose `@note` or body covers the meaning
of an inline annotation on a map row, array literal, or magic
constant inside the entity, **remove** that inline annotation.
Leaving it duplicates what the docstring says.
- If you wrote a docstring on a function whose body has line-by-line
narration of control flow (`// check this`, `// now do that`),
**remove** the narration unless a specific line documents a real,
non-obvious WHY.
- Section banner comments (`// --- Avalanche tuning ---`) may stay as
short visual dividers if they help scanning a long struct, but any
multi-line prose in them that is now in the per-field Doxygen
should be cut.
5. **Do not delete** comments that capture a WHY the docstring does not
cover: a workaround for a real bug, a non-obvious invariant local to
one branch, a reference to a ticket or RFC. If a pre-existing
comment contains information you did not put in the new docstring,
either fold it into the docstring or leave it in place.
## Worked examples
These show the exact transformations expected. The "AFTER" column is the
state the file must be in when you finish. If your edit leaves the file
in the "BEFORE" state, the pass has failed.
### Example 1: section-header prose → short banner
BEFORE:
```cpp
//-------------------------------------------------------------------------
// Validation and proposal durations are relative to NetClock times, so use
// second resolution
/** Maximum age of a validation relative to its ledger's close time.
* ... (rest of docstring already explains NetClock semantics) ...
*/
std::chrono::seconds const validationVALID_WALL = std::chrono::minutes{5};
```
AFTER:
```cpp
// --- NetClock-domain parameters ---
/** Maximum age of a validation relative to its ledger's close time.
* ... (rest of docstring already explains NetClock semantics) ...
*/
std::chrono::seconds const validationVALID_WALL = std::chrono::minutes{5};
```
The multi-line prose was redundant with the new per-field Doxygen and the
file-level `@file` block. Replace with a single-line banner.
### Example 2: inline annotations on a data literal → removed
BEFORE:
```cpp
/** Avalanche state machine cutoffs.
*
* | State | Time | Yes-vote | Next |
* |--------|------|----------|--------|
* | Init | 0 | 50 | Mid |
* | Mid | 50 | 65 | Late |
* ...
*/
std::map<AvalancheState, AvalancheCutoff> const avalancheCutoffs{
// {state, {time, percent, nextState}},
// Initial state: 50% of nodes must vote yes
{AvalancheState::Init, {.consensusTime = 0, .consensusPct = 50, .next = AvalancheState::Mid}},
// mid-consensus starts after 50% of the previous round time, and
// requires 65% yes
{AvalancheState::Mid, {.consensusTime = 50, .consensusPct = 65, .next = AvalancheState::Late}},
// ...
};
```
AFTER:
```cpp
/** Avalanche state machine cutoffs.
*
* | State | Time | Yes-vote | Next |
* |--------|------|----------|--------|
* | Init | 0 | 50 | Mid |
* | Mid | 50 | 65 | Late |
* ...
*/
std::map<AvalancheState, AvalancheCutoff> const avalancheCutoffs{
{AvalancheState::Init, {.consensusTime = 0, .consensusPct = 50, .next = AvalancheState::Mid}},
{AvalancheState::Mid, {.consensusTime = 50, .consensusPct = 65, .next = AvalancheState::Late}},
// ...
};
```
The per-row inline comments restate the table that is now in the
docstring above. They go. The schema comment `// {state, {time, percent, ...}}`
also goes — the designated-initializer field names make the schema obvious.
### Example 3: body narration in a documented function → removed
BEFORE:
```cpp
/** Query the avalanche state machine.
* ...
* @note `at()` calls on `avalancheCutoffs` are safe because the map is
* constructed with all four valid keys.
*/
inline std::pair<...> getNeededWeight(...)
{
// at() can throw, but the map is built by hand to ensure all valid
// values are available.
auto const& currentCutoff = p.avalancheCutoffs.at(currentState);
// Should we consider moving to the next state?
if (currentCutoff.next != currentState && currentRounds >= minimumRounds)
{
// at() can throw, but the map is built by hand to ensure all
// valid values are available.
auto const& nextCutoff = p.avalancheCutoffs.at(currentCutoff.next);
// See if enough time has passed to move on to the next.
XRPL_ASSERT(...);
if (percentTime >= nextCutoff.consensusTime)
{
return {nextCutoff.consensusPct, currentCutoff.next};
}
}
return {currentCutoff.consensusPct, {}};
}
```
AFTER:
```cpp
/** Query the avalanche state machine.
* ...
* @note `at()` calls on `avalancheCutoffs` are safe because the map is
* constructed with all four valid keys.
*/
inline std::pair<...> getNeededWeight(...)
{
auto const& currentCutoff = p.avalancheCutoffs.at(currentState);
if (currentCutoff.next != currentState && currentRounds >= minimumRounds)
{
auto const& nextCutoff = p.avalancheCutoffs.at(currentCutoff.next);
XRPL_ASSERT(...);
if (percentTime >= nextCutoff.consensusTime)
{
return {nextCutoff.consensusPct, currentCutoff.next};
}
}
return {currentCutoff.consensusPct, {}};
}
```
Every removed comment was either restating what the next line does
(`// Should we consider moving to the next state?` on an `if`) or
duplicating the docstring's `@note` (`// at() can throw...`). None of
them documented a non-obvious WHY local to that line.
### Calibration: when an inline comment STAYS
If the body contains a comment that documents a real local WHY —
something the function-level docstring cannot reasonably hold — keep it.
```cpp
// Workaround for boost #12345: pass nullptr instead of the empty buffer.
boost::asio::buffer(nullptr, 0);
// We deliberately do not lock here: the caller is required to hold
// lock_ across this method and the recursion would deadlock.
internalUpdate();
```
These are non-removable. They are not restating the code; they are
explaining something the reader cannot derive from the line.
## Rules that apply throughout
- Do NOT modify code logic — only adjust comments and Doxygen.
- Do NOT document entities that don't need it (private members with
obvious purpose, trivial defaulted constructors, getters whose name is
self-explanatory).
- Do NOT read the `.ai.md` file yourself — it is already in your prompt
if one exists for this file.
- If "Authoritative AI Context" is provided in the user prompt, treat it
as the source of truth for the file's intent and behavior. Your task
is to translate that prose into Doxygen on the actual declarations.
When you finish, summarize:
- How many entities you documented

30
.github/scripts/doc-agent/prompts/regen-skill.md vendored
View File

@@ -39,9 +39,29 @@ ai.md files into the existing skill. Specifically:
- **Keep prose grounded.** No marketing language. No "robust, scalable,
enterprise-grade" filler. Engineers reading this need facts.
## Output
## Output — Chunked Writing (REQUIRED)
Emit the complete new skill file content as your final assistant message.
Start with the markdown heading. Do not include meta-commentary like "Here
is the updated skill file" — the output is captured verbatim and written
to the skill file path.
You have a per-turn output cap (32K tokens). For larger modules, a
complete skill file will not fit in a single tool call. You MUST write
the file in chunks across multiple tool calls. Do not try to emit the
whole file in one Write — it will be truncated mid-content.
Process:
1. **First chunk (Write)**: Call the `Write` tool with the start of the
skill: the title heading, the opening overview, and the first 1–2
major sections. Keep this chunk under ~20K characters of content.
2. **Subsequent chunks (Edit)**: For each remaining section, call the
`Edit` tool with:
- `old_string` = the last line currently at the end of the file (must
be unique enough to match unambiguously — use the full last line)
- `new_string` = that same last line **plus the next 1–2 sections**
appended
Keep each chunk under ~20K characters.
3. **Repeat** until the skill is complete. There is no maximum number
of Edit calls.
After the file is fully written, respond with a one-line confirmation
listing how many chunks you wrote.
DO NOT emit the skill content in your text response. The file is the
output; the text response is only for confirmation.

22
.github/scripts/doc-agent/src/regen-skills.ts vendored
View File

@@ -122,22 +122,30 @@ When you have written the file, respond with a brief one-line confirmation.`;
model: MODEL,
systemPrompt,
cwd: XRPLD_ROOT,
allowedTools: ['Write', 'Read', 'Glob', 'Grep'],
allowedTools: ['Write', 'Edit', 'Read', 'Glob', 'Grep'],
permissionMode: 'acceptEdits',
},
});
let wroteFile = false;
let writeCount = 0;
let editCount = 0;
for await (const message of result) {
if (message.type === 'assistant') {
const content = message.message?.content;
if (Array.isArray(content)) {
for (const block of content) {
if (block.type === 'tool_use' && block.name === 'Write') {
writeCount++;
const input = block.input as { file_path?: string } | undefined;
if (input?.file_path !== undefined) {
wroteFile = true;
console.log(` Agent wrote: ${input.file_path}`);
console.log(` Write: ${input.file_path}`);
}
}
if (block.type === 'tool_use' && block.name === 'Edit') {
editCount++;
const input = block.input as { file_path?: string } | undefined;
if (input?.file_path !== undefined) {
console.log(` Edit: ${input.file_path}`);
}
}
}
@@ -145,14 +153,14 @@ When you have written the file, respond with a brief one-line confirmation.`;
}
if (message.type === 'result') {
const cost = message.total_cost_usd?.toFixed(4) ?? '?';
console.log(` [Cost: $${cost}]`);
console.log(` [Cost: $${cost}]`);
}
}
if (!wroteFile) {
if (writeCount === 0) {
console.error(' Agent did not call Write — skill file not updated.');
return;
}
console.log(` Wrote: ${skillRelPath}`);
console.log(` Wrote: ${skillRelPath} (${writeCount} Write + ${editCount} Edit calls)`);
}