Designing a Proposal That Answers 'Did You Look Into This?' — Cutting 260 Lines Down to 53

In the previous post, I wrote about arriving at the "investigation recipe" approach the day after shelving autonomous agents.

Around the time the investigation recipe design was coming together, a different problem surfaced.

"The proposal is hard to read."

The moment I heard it, I agreed — but honestly couldn't immediately see what to fix. When I reviewed the structure with Claude Code, the cause turned out to be surprisingly simple. I was saying the same thing three times.

What was wrong

The original proposal document had this structure:

- Executive summary
- §1: Starting analysis
- §2: Approach comparison
- §3: Approach B (investigation recipe method)
- §4: Next actions
- §5: Remaining considerations

Looks logical. But reading through — the executive summary says "recommend Approach B," §2 writes "the rationale for recommending Approach B," and §3 writes "details of Approach B." The same conclusion appears three times.

When Claude Code pointed this out, it clicked immediately. While writing, you think about each section independently so you don't notice. But from the reader's perspective, they're reading paraphrases of the same content over and over.

Redefining the proposal's purpose

Before rewriting, I first asked: "who is this document for, and what should it do?"

When bringing a draft to stakeholders, this kind of question comes up all the time:

"What's the status on this? Did you look into it?"

If handing over the proposal still requires explaining from scratch on the spot, that defeats the purpose. Being able to say "yes, that's covered here — see this section for details" should be enough.

The proposal's role was not to pack in all decision-making materials, but to provide an index of investigated topics. This realization changed the structure significantly.

The structure after cutting

The new 5-section structure:

1. What this document is
   Draft. A snapshot for answering "did you look into this?"

2. What we're currently thinking
   Approach B (investigation recipe) in a few lines + links to detail docs

3. Why we think that
   Key points from 94-incident analysis and comparison only (3-5 lines each) + links

4. What we've investigated so far (index table)
   One line per document. Current status marked (mainline/on-hold/asset/independent)

5. What we want to discuss / undecided items
   Bullet points of open questions only

What was cut:

What was kept:

Result: 260 lines → 53 lines. Not just halved — quartered.

After cutting, you can grasp what we're currently thinking and what's undecided in 1–2 minutes. Information density is actually higher than when everything was packed in. Paradoxically, cutting can increase the amount that gets through.

Terminology must match the concept

During the document cleanup, another concern emerged: a terminology problem.

The word "PSIRT" appeared several times in the documentation. Internally, an existing Excel sheet was called "PSIRT table," and the term had naturally propagated through citations.

But PSIRT (Product Security Incident Response Team) is a security-incident-specific term. What we're dealing with — DB column overflow, table sync gaps, external API failures — are general development incidents, not security-specific.

The concept doesn't match.

This kind of cleanup requires care. The "PSIRT table" Excel sheet name is an internal proper noun being cited — changing it unilaterally would be overstepping. However, a repository name I'd newly proposed contained "psirt," and that could be fixed.

The cleanup:

Minor edits, but necessary to prevent future readers from wondering "why is a security term being used here?" When terminology and concept are misaligned, unnecessary friction appears while reading. That friction gets in the way of the actual discussion.

The words used in documents should match the concepts they point to. Easy to overlook while writing, though.

Current state

The document set now looks like this:

docs/impact-analysis/
├── 01-proposal.md               Overall direction (restructured around Approach B)
├── 02-incident-analysis.md      94-incident analysis details
├── 03-approach-comparison.md    Approach comparison
├── 04-rule-management.md        Playbook design (legacy asset)
├── 05-agent-design.md           Agent design (legacy asset)
├── 06-review-recipe.md          Investigation recipe approach draft (current mainline)
├── 07-autonomous-agent-approach.md  Autonomous investigation (on-hold alternative)
├── 08-derivative-initiatives.md    Derivative measures (4 items)
├── 09-incident-data-management.md  Incident data management
├── 10-operations-coordination.md   Stakeholder coordination matters
└── 11-phase0-work-guide.md         Phase 0 work guide

With 01-proposal.md functioning as a "snapshot," questions like "what's the status here?" can be answered with "see doc 04" or "the hold rationale is summarized in 07."

We're now at the stage of moving into stakeholder conversations with this in hand. Concrete topics like Phase 0 execution planning (PR selection, evaluation sheet design) and whether to proceed with derivative measures first are still ahead. More to come.

Further reading

If you want to go deeper on structuring technical documents and writing that communicates effectively, this book is a good starting point.