14.3 Using AI to Draft and Iterate on Specs

Writing a complete spec from a blank page is hard work, and it is exactly the kind of task where modern AI assistants pay for themselves. An assistant cannot replace the analyst’s domain conversations or judgment calls, but it can do three things very well: produce a competent first draft, suggest questions the analyst forgot to ask, and stress-test the logic of a draft before the stakeholder ever sees it.

14.3.1 A first-draft prompt

A useful prompt for an initial spec draft tells the assistant exactly which template to follow and feeds it the discovery notes from Section 1. For example:

“You are a senior BI analyst. Using the BRS template from the textbook (Problem Statement, Key Questions, Target Audience, Deliverables, KPIs, Timeline, Constraints), draft a Business Requirements Specification for the following project. Do not invent stakeholders or constraints that are not explicitly stated in the notes; flag any field where you would need more information from the analyst.

Discovery notes:

HR director of a Brazilian courier company; uses results to design an upcoming wellness program.

Two-week deadline; check-in at end of week 1.

‘Chronic’ absenteeism defined as more than 40 hours per quarter (HR’s prior internal report).

Audience: HR managers and senior leadership; non-technical.

Cannot use gender, ethnicity, or religion as predictors.”

Notice three deliberate features of this prompt. First, the assistant is given a role (“senior BI analyst”) and a fixed template, which sharply reduces hallucination. Second, the notes are explicit and bulleted, leaving no room for the assistant to invent context. Third, the prompt explicitly invites the assistant to push back where information is missing — a step that catches gaps before they become problems.

14.3.2 Iterating on the draft

The assistant’s first draft will rarely be production-ready. Treat each output the way you would treat a junior analyst’s first attempt: read it critically, mark what is wrong, and ask for a specific revision rather than a wholesale rewrite. Useful follow-up prompts include:

“Rewrite the Key Questions so each one is answerable with a specific analytical artifact.”
“The 70% accuracy KPI is currently unmeasurable as written. Specify how it should be measured (training vs. held-out test set, balanced vs. imbalanced sampling).”
“Identify three constraints from the discovery notes that I have failed to encode in the draft.”

The third prompt is the most valuable. It uses the assistant adversarially: instead of generating new content, it audits the analyst’s own work for omissions. This is a low-cost, high-yield use of AI in spec-driven workflows.

14.3.3 Ethical guardrails

Two warnings are worth stating explicitly. First, do not paste real, confidential, or personally identifiable data into a public AI chat window unless your organization has a vetted enterprise tool with appropriate data-handling guarantees. The discovery notes above describe a project, not a person — that is the kind of context an external assistant can safely consume. Second, the assistant’s draft is your draft once you ship it. Read every line; assistants confidently produce plausible nonsense, particularly in numeric KPIs and timelines, and the analyst’s name (not the model’s) goes on the deliverable.

Multiple ways: where to use AI in the spec workflow

There is no single “right” place to involve an AI assistant in spec writing. Three patterns work well in practice:

AI-first. The analyst feeds discovery notes to the assistant, gets a complete draft back, then edits it.
Human-first. The analyst writes the spec, then asks the assistant to critique it and identify missing constraints.
Section-by-section. The analyst writes the BRS by hand, but uses the assistant to draft the data dictionary directly from the dataset. Data dictionaries are tedious and AI excels at them.

The choice depends on which step is most expensive for the analyst. For new analysts, AI-first lowers the barrier; for experienced analysts, human-first preserves judgment while still catching blind spots.

With a spec in hand, the project is ready to be built. We turn next to executing the spec in R.