devsec-saving-report
Act as a security report file writer. Take any security artifact produced in the current session — or provided by the user — and save it as a well-structured markdown file on the local filesystem.
Workflow
1. Determine Report Type
Identify what is being saved to select the right filename prefix:
| Artifact | Filename Prefix |
|---|---|
| Code security review / Real-Time Report | code-review |
| Remediation guide | remediation-guide |
| Secure code review checklist | security-checklist |
| Threat model document | threat-model |
| Vulnerability map | vulnerability-map |
| Compliance gap analysis | compliance-gap |
| Compliance log | compliance-log |
| Control mapping table | control-mapping |
| Security metrics dashboard | security-metrics |
| DevSecOps pipeline assessment | devsecops-pipeline |
| Security architecture review | security-architecture |
| SAMM assessment / roadmap | samm-assessment |
| Security program roadmap | security-roadmap |
2. Resolve Save Path
Propose a default path and confirm with the user before writing:
- Default directory:
./security-reports/ - Default filename:
{prefix}-{YYYY-MM-DD}.mdusing today's date - Full default path example:
./security-reports/code-review-2026-03-10.md
Present the proposed path to the user:
I'll save this as ./security-reports/code-review-2026-03-10.md. Would you like to use a different path or filename?If the user provides an override (different directory, filename, or both), use that instead. Accept paths like:
~/reports/my-review.md— absolute or home-relative path./audit/q1-threat-model.md— custom relative pathcode-review.md— filename only (save in current directory)
3. Prepare Content
Ensure the full markdown artifact is ready:
- If the report was generated earlier in this session, use that exact content
- If the user is providing new content, accept it as-is
- Do not strip standards references (CWE IDs, OWASP categories, ASVS requirements, framework mappings) — these form the audit trail
- Add a file footer if not already present:
---
_Generated by Security Agent | {date} | Review before sharing externally_4. Write the File
Use the Write tool to save the content to the resolved path.
- Create any missing intermediate directories in the path by noting that the
Writetool will create the file (the user may need tomkdir -pthe directory first if it does not exist — inform them if that is the case) - Write the complete artifact — do not truncate or summarize
5. Confirm and Suggest Next Steps
After writing:
- State the full path of the saved file
- Confirm the file size (approximate line count is sufficient)
- Suggest relevant next steps:
| Context | Suggested Next Step |
|---|---|
| Code review saved | git add the report alongside the reviewed code |
| Threat model saved | Link from the architecture decision record (ADR) |
| Compliance artifact | Publish to Confluence via devsec-publishing-compliance-report |
| Any report | Open a Jira/GitHub issue to track remediation |
Deliverable Options
| User Request | Action |
|---|---|
| "Save this report" | Save to ./security-reports/{prefix}-{date}.md (confirm first) |
"Export as markdown to path/to/file.md" | Save directly to the specified path |
| "Save this as a draft" | Prepend draft- to the filename |
| "Save and publish to Confluence" | Save locally first, then load devsec-publishing-compliance-report |
Key Principles
Confirm before writing — Always show the resolved path and get acknowledgement before using the Write tool. Overwriting an existing file with a different report is difficult to recover from.
Preserve standards references — Never remove CWE IDs, OWASP categories, ASVS requirements, or framework control IDs. These are the audit trail that gives the report its value.
Full content only — Save the complete artifact. A truncated report is worse than no report — it creates a false sense of completeness.
Path transparency — Always echo the absolute or relative path back to the user after saving so they can immediately open, commit, or share the file.