Create Follow-Up Request

Contributors🕹️Paul Atkins

Purpose

Generate a structured .md file that a business user can paste into their LLM-powered editor to produce a technical supplement. The request identifies information gaps from a gap analysis and remediation plan, and guides the user through collecting the missing data from their codebase.

When to use

• Gap analysis reveals assumptions that need validation against actual code
• Remediation plan contains work items where effort depends on unknown details
• Technical architecture documentation is incomplete or may have drifted from code
• You need codebase inspection data that only the system owner can provide

Prerequisites

1. Completed gap analysis — with identified gaps and assumptions
2. Remediation plan (optional but recommended) — helps identify which gaps are highest priority

Instructions

Step 1 — Identify information gaps

Read the gap analysis and plan. For each gap or assumption, ask: "What information from the actual codebase would confirm or change this?"

Categorise gaps into section types:

Type	Badge	What to ask for	Example
Copy file	📄	Full file contents in a code block	requirements.txt, Dockerfile, package.json
Code review	🔍	Browse code and summarise findings	Error handling patterns, API route inventory
Run & report	📊	Run a command and paste output	Test count, git log, database size

Step 2 — Design the request document

Use this structure:

# [System Name] — Additional Technical Detail Request

> **To:** [recipient role]
> **From:** [your team]
> **Date:** [date]
> **Audience:** Someone with local access to the [system] codebase
> **Estimated effort:** [time estimate]

## What is this?
One paragraph explaining context and why you need this.

## Section type legend
Table mapping badges to actions (📄 Copy file, 🔍 Code review, 📊 Run & report).

## How to generate this
Step-by-step instructions for using an LLM to produce the output.
Include the exact prompt they should paste.

## Sensitive data redaction checklist
Checklist of what to redact before sharing.

## Prerequisite check
Checklist of files the user should confirm exist before starting.

## Sections needed
Numbered sections, each with:
- Type badge (📄, 🔍, or 📊)
- Clear title
- What to provide and why
- Example of expected format
- "If it doesn't exist, write 'Not present in this codebase'"

## Output format
How to combine sections into a single output file.

## Completion checklist
Before-sending verification checklist.

Step 3 — Write the LLM prompt

Include a ready-to-paste prompt block that the user feeds to their LLM:

> I need to generate a technical supplement for [system]. For each of the
> N sections below, output the requested information based on the actual
> codebase. Format the output as a single markdown file called
> `[SYSTEM]_TECHNICAL_SUPPLEMENT.md`. Use code blocks for file contents.
> If a requested file doesn't exist, write "Not present in this codebase"
> for that section. Do NOT include any sensitive values — see the redaction
> checklist below.

Step 4 — Write the redaction checklist

Always include guidance on redacting:

• Passwords, API keys, tokens, secrets
• Database hostnames and ports (keep localhost/placeholders)
• Tenant IDs, workspace URLs, authentication details
• Real server IPs or domain names
• Personal names or usernames in file paths
• Real data (trade data, customer names, counterparty identifiers)
• Proprietary business logic, algorithms, formulas
• Internal registry URLs

Use the pattern: "Replace with <REDACTED>" or domain-specific tags like <TRADING_LOGIC_REDACTED>.

State what IS safe to share: file names, dependency versions, error response shapes, test file names, log format (not content), route paths, component names.

Step 5 — Prioritise sections

Order sections by: 1. P0 blockers — information that blocks the highest-priority plan items 2. Assumption validators — data that confirms or invalidates key assumptions 3. Nice-to-have — useful context but plan can proceed without it

Step 6 — Usability review

Before finalising, check for these common issues:

Issue	Fix
Sections require domain expertise the user may not have	Add examples of expected output
Instructions are ambiguous ("provide relevant code")	Be specific ("paste the contents of logging_setup.py")
No fallback for missing files	Add "If not present, write 'Not present in this codebase'"
Redaction guidance is generic	Make it specific to the domain (trading logic, customer data)
No estimated effort	Add a time estimate (helps the user plan)
Too many sections	Consolidate related asks; aim for 10–20 sections max
Prompt is too long for a single LLM context	Split into two requests with clear part numbering

Output

A single .md file named [system]-technical-detail-request.md (or -clarification-questions.md for shorter follow-ups) in the workspace root.

Two output formats

Full technical supplement request

For initial data gathering (10–20 sections, LLM-promptable, 📄/🔍/📊 badges). Use when you have many unknowns.

Short clarification questions

For targeted follow-up (3–8 questions, human-answerable, inline response format). Use when you have specific questions after reviewing a supplement. Structure:

### N. [Topic]
[Context sentence]
- [Specific question 1]
- [Specific question 2]
> _Answer:_

Troubleshooting

Error: Business user returns incomplete supplement — many "Not present" responses. Cause: Prerequisite check wasn't done; files are in unexpected locations. Solution: Ask user to run find . -name "*.py" | head -30 (or equivalent) and share the folder structure so you can adjust file paths.

Error: Supplement contains sensitive data despite redaction checklist. Cause: User didn't review the checklist or LLM didn't apply it. Solution: Flag specific instances and ask for re-redaction. Do not store or forward the sensitive version.

Error: Supplement contradicts the architecture document. Cause: Architecture doc has drifted from code (common with rapidly developed prototypes). Solution: Trust the supplement (it's from the actual codebase). Update gap analysis and plan with the corrected information using update-plan-from-evidence.