docs: align write-up report naming with the findings schema - #204
Open
mariohercules wants to merge 1 commit into
Open
docs: align write-up report naming with the findings schema#204mariohercules wants to merge 1 commit into
mariohercules wants to merge 1 commit into
Conversation
The findings schema requires a write-up's file name to equal its
directory slug:
"pattern": "^findings/([a-z0-9][a-z0-9._-]*)/\\1\\.md$"
The orchestrating skills state that convention, but the write-up skill
that actually creates the file asked for an "appropriately-named" report
with two differing example file names, neither of which satisfies the
pattern. The sub-agent prompt template passed only an output directory,
so the constraint never reached the worker.
State the `findings/<slug>/<slug>.md` rule in the skill, the report
format reference, and the sub-agent prompt, while keeping the original
intent that the slug stay descriptive rather than `report`.
Fixes openai#47
mariohercules
force-pushed
the
fix/writeup-report-filename
branch
from
August 1, 2026 23:42
06b5993 to
8afc257
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #47.
Problem
The findings schema requires a write-up's file name to equal its directory slug, via a backreference:
The orchestrating skills state that convention (
deep-security-scan,security-diff-scan,references/scan-artifacts.md,references/final-report.mdall sayfindings/<slug>/<slug>.md). Butvulnerability-writeup— the skill whose sub-agent actually creates the file — asked for an "appropriately-named" report and gave two different example file names, neither of which satisfies the pattern. Its sub-agent prompt template passed onlyOutput directory: <reports-dir>/<slug>, so the constraint never reached the worker.Checked against the plugin's own validator (
finalize_scan_contract.validate_against_schema):The two rejected names are exactly the examples the guidance gave. When the worker follows them, either finalization rejects the document at seal time — after all analysis work is done — or
writeup.reportPathpoints at a file that does not exist.Change
State the
findings/<slug>/<slug>.mdrule in three places that previously contradicted it:skills/vulnerability-writeup/SKILL.mdstep 7skills/vulnerability-writeup/references/report-format.mdThe original intent is preserved: the slug must stay descriptive, so
reportis still called out as the thing not to fall back to.Notes
This is documentation only — no behavior change, and the schema already enforces the rule at runtime. I did not add a test: the repository has no harness for skill prose, and a text-matching assertion would be brittle without catching the real invariant.
Verified on this branch:
pnpm run types,pnpm run format,pnpm run check:packageall clean, and the full suite passes (717 pass, 5 skip, 0 fail).