move skills

.github/scripts/doc-agent/prompts/document-file.md

@@ -34,7 +34,7 @@ Read `docs/DOCUMENTATION_STANDARDS.md` for the full specification. Key rules:
 
 ## Module Context
 
-Before you start, read the relevant skill file in `docs/skills/soul/` for
+Before you start, read the relevant skill file in `docs/skills/` for
 the module you're working on. These capture per-module conventions, key
 classes, and gotchas:
 
@@ -42,20 +42,26 @@ classes, and gotchas:
 - `protocol` — STObject, SField, Serializer, TER codes, Features, Keylets
 - `ledger` — ReadView/ApplyView, state tables, payment sandbox
 - `tx` / `transactors` — transaction pipeline
-- `consensus`, `peering`, `nodestore`, `shamap`, `rpc` — see `docs/skills/soul/`
+- `consensus`, `peering`, `nodestore`, `shamap`, `rpc` — see `docs/skills/`
 
 ## Process
 
-1. Read the target file completely
-2. Read the corresponding skill file in `docs/skills/soul/` if one applies
-3. Identify entities that need documentation (public classes, structs,
+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)
-4. For each entity: read the implementation (and tests if helpful), then
-   write a Doxygen comment that captures behavior and intent
-5. Use the Edit tool to add the comments to the file
-6. Do NOT modify code logic — only add documentation
-7. Do NOT add documentation to entities that don't need it (private members
+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
 
 When you finish, summarize:
 - How many entities you documented

.github/scripts/doc-agent/prompts/regen-skill.md

@@ -0,0 +1,47 @@
+You are updating a per-module skill file for the xrpld codebase.
+
+A "skill" is a single markdown file at `docs/skills/<module>.md` that
+captures the institutional knowledge for one module: what it does, key
+classes, conventions, gotchas, and how to work in it. The skill file is
+loaded as context whenever an agent works on code in that module.
+
+## Inputs
+
+You will be given:
+- The current skill file for the module (the baseline to update)
+- A list of `.ai.md` files describing the source files in this module
+  (one per source file, with high-signal prose about purpose and design)
+
+## Your task
+
+Produce a new, improved skill file that integrates the knowledge from the
+ai.md files into the existing skill. Specifically:
+
+1. Update the description of the module's responsibility if the ai.md files
+   reveal more accurate or detailed framing
+2. Add any classes, patterns, or invariants the skill is missing
+3. Update lists of key files / entry points / conventions
+4. Add gotchas and non-obvious behavior surfaced by the ai.md files
+5. Keep the structure of the existing skill (don't reorganize for the sake
+   of it — only restructure if the existing structure is genuinely failing)
+6. Be terse. A skill file is a reference card, not a textbook. 200-500 lines
+   is typical; over 1000 means you're padding.
+
+## Quality rules
+
+- **Do not duplicate the ai.md content.** Aggregate, synthesize, distill.
+  The skill is the module-level view; individual file details belong in
+  ai.md (and eventually in inline Doxygen comments).
+- **Preserve accurate existing content.** Don't rewrite working sections.
+- **Cite file paths** for specific claims (e.g., "see `STAmount.h:roundToScale`").
+- **Flag contradictions.** If two ai.md files describe the same concept
+  differently, surface the conflict rather than silently picking one.
+- **Keep prose grounded.** No marketing language. No "robust, scalable,
+  enterprise-grade" filler. Engineers reading this need facts.
+
+## Output
+
+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.