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}.md using 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 path
• code-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 Write tool will create the file (the user may need to mkdir -p the 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.