findings-writer

name	findings-writer
description	Write professional smart contract security findings and append them to a file. Trigger this skill when the user types the command /write-the-finding (case-insensitive).

Smart Contract Security Findings Writer

Convert vulnerabilities discussed in conversation into clear, concise, judge-proof security findings and append them to a specified file.

Findings are formatted for audit platforms: Code4rena, Sherlock, Cantina, Immunefi, or similar.

The skill accepts flags in any order: -file (markdown file to write to), severity as H, M, or L (High, Medium, Low), platform as Code4rena, Sherlock, Immunefi, or Cantina (case-insensitive). If any flag is missing, ask for it before proceeding.

---

Inputs

The skill is triggered exclusively by the slash command:

/write-the-finding -file <filename> -severity <H|M|L> -platform <platform>

Flags (any order, case-insensitive):

Flag	Values	Description
-file	any filename	Markdown file to append the finding to
-severity	H, M, L	Maps to High, Medium, Low
-platform	Code4rena, Sherlock, Immunefi, Cantina	Target submission platform (case-insensitive)

Examples:

/write-the-finding -file findings.md -severity H -platform sherlock
/write-the-finding -platform Cantina -severity m -file audit/issues.md

If any flag is missing, ask for it before proceeding. The vulnerability content comes from the current conversation context.

---

Your Responsibilities

1. Identify the vulnerability from the conversation or user input
2. Write a complete, professional finding
3. Format it per the target platform's style
4. Append it to the provided file (never overwrite)
5. Confirm to the user what was written and where

---

Writing Rules

1. Extremely Clear and Simple

• Write in plain, direct English
• Judges must understand the issue immediately
• Avoid: complicated language, unnecessary theory, long paragraphs
• Prefer: short explanations, structured sections, direct statements

2. Impossible to Invalidate

• Base all arguments on code behavior
• Avoid speculation or hypothetical claims without proof
• Prove the issue with: code references, logical reasoning, clear impact explanation

3. Concise but Complete

• Short enough to read in under 1 minute
• No filler text - every sentence must add value

4. Code References with Relative Links

Always use relative markdown links when referencing code:

[Contract.sol:123](path/to/Contract.sol#L123)
[transfer() implementation](src/token/Token.sol#L45)

5. Reference Protocol Documentation When Useful

Link to README, invariants, or design docs to strengthen the argument:

[README: liquidation assumptions](README.md#liquidation-model)

6. Show Real Impact

Every finding must explain:

• what goes wrong
• when it happens
• why it matters

Avoid vague statements like "may cause issues." Say instead:

"This allows a user to withdraw more tokens than deposited."

---

Finding Structure

Use this structure unless the platform requires otherwise:

## Title
Short, direct description of the issue.
 
## Summary
2-3 sentences: what the issue is, where it happens, what the consequence is.
 
## Root Cause
Exactly why the vulnerability exists. Include code references.
 
## Vulnerability Details
Step-by-step explanation of the faulty logic and resulting incorrect state.
 
## Impact
Real consequence - who can exploit it, what they gain.
Examples: funds stolen, tokens minted without backing, invariants broken.
 
## Proof of Concept (if applicable)
Minimal steps to trigger the issue. No full test unless necessary.
 
## Mitigation
Simple, concrete fix suggestion.

---

Platform Formatting

Platform	Style
Code4rena	Standard markdown sections
Sherlock	Concise markdown issue format
Cantina	Structured markdown issue
Immunefi	Impact-driven report

Always preserve the same logical sections regardless of platform.

---

File Handling

Append findings to the provided file in this format:

---
 
## [Severity] Finding Title
 
(full finding content)
 
---

Never overwrite existing findings. Always append at the end.

If the file does not exist, create it with a header:

# Security Findings

---

Tone

• Professional, confident, factual, neutral
• Do NOT exaggerate impact
• Arguments must stand on clear logic and code references

---

Goal

Produce findings that:

• Judges can read quickly and understand immediately
• Are difficult to dispute
• Clearly demonstrate a real vulnerability
• Look professional and audit-quality