This article is for everyone who struggles with writing good reports (95% of this space). I'll keep the explanations short (to match your attention span) and provide more examples.

It's really important to write good reports. That skill purely effects your payout, as you can be a really good auditor, but bad reports will consistently get your findings invalidated or marked as 50% (half the payout). Also if you are the only one reporting this issue, a good report can be the difference between invalid and solo. Finally if you are really good at writing reports you can get "selected for report", a nice title with 30% reward increase for this issue.

Make it simple

Be sure, even if the judge hasn't looked at the code-base yet, when he reads your report he will know what you are talking about. Simple, clear, straight to the point.

Use ChatGPT

Compose the report yourself and use GPT to enhance its structure and remove any grammar mistakes. If you are like me, you'll find it quite useful.

Here's my approach:

paste the report

If you're good with how you've set things up and the words you've chosen, go ahead and "check for grammar." If you want to make your description sound better, you can "improve on the report." And if the words seem a bit too complicated, just "use simpler words." But sometimes, these choices can be a bit much – either too complicated or too simpler. If that's the case, you can "use simpler words, preferably grade (pick one from 8-12) reading"

Do a POC if you have time

This helps avoid the 50% mark and brings you closer to being the selected report. However, just having a POC won't make you selected. You also need a well-presented report. And for god' sake, put those POCs in a Gist, don't simply insert 500 lines of code into the report.

Use fancy math

Always use markdown mathematical formulas (using $$), if there is math involved.

You can:

toleratedGaugeWeight = 80000e18 * 1.2e18 / 1e18 = ...

However it looks 5x better if you do it the correct way. You insert the formula into GPT and let it write it for you.

I use:

"represent this formula in .md mathematical format using $$"

paste math here

More links, the better

Every time you reference a function, make it a link, firstly they add some color to your report, making is less blunt, and secondly they make it really easy to follow with the main code.

" Due to the nature of how ArcadeAirdrop is made and the expectation that there might be a change in the Merkle tree in the near future, users will expect to be able to claim the extra rewards (if they are increased on Merkle root). However, because there is a problematic if statement (that is inherited in ArcadeAirdrop by ArcadeMerkleRewards) users that have already claimed their rewards will have no share of the future ones. "

Tell me, doesn't the above look better that this bellow? If you think it's the same, you have a bad taste.

" Due to the nature of how ArcadeAirdrop is made and the expectation that there might be a change in the Merkle tree in the near future, users will expect to be able to claim the extra rewards (if they are increased on Merkle root). However, because there is a problematic if statement (that is inherited in ArcadeAirdrop by ArcadeMerkleRewards users that have already claimed their rewards will have no share of the future ones. "

Make good resolutions

After completing the report, consider the best solution you can implement. If it involves code that needs to be redone, use diff, this makes the solution appear extremely simple.

See how clear the one below is. It clearly highlights the issue we have.

If you encounter an issue for which you don't have a clear solution, it's better to admit uncertainty than to suggest something useless.

"Because I am unsure of how the developers want this protocol to function, I am unable to propose an effective solution to resolve this issue. Significant parts of the system need to be redone."

"Because this issue relates to the overall structure of the protocol, and not some specific one liner issue, I am unable to give an exact solution."

Use tables for examples with a lot of prerequisites

This is an area where providing examples in bullet points can make your report long and boring.

• the size of the pool is 10,000 tokens

• the max LTV is 50%

• and so on...

Can you imagine yourself writing all these as bullet points? Why not use the table below, it's a great summary and it looks amazing!

Use the solidity tag instead of jsx

That may be obvious, but some of you mules are still marking your Solidity code with jsx (I also was one of these mules D: ). This is really annoying because some things have color while others don't. It gives this feeling that it's your first report ever.

Finally, after completing most or all of the tasks, there's no guarantee your report will be chosen. If you believe your explanation is the best, wait for the escalation period and then explain why your report is actually the best. Sometimes, the judge has too many things on their mind and may not thoroughly compare all the reports. This is why you should comment and escalate with a clear description stating why your report is better.

For example: The currently selected report looks good, however, I believe this one highlights the issue more clearly (selfishly pointing to my report). The report is simpler and easier to understand, with a more in-depth explanation, a great solution, and even includes a runnable POC!

If you enjoyed this article, feel free to tweet it out. This way, we can help share knowledge faster. See you next time.