MentoringBA BA Automation Lab

Automate the paperwork. Keep the judgement.

A hands-on course for Business Analysts. You will use an AI agent to draft requirements, user stories, tests and traceability from stakeholder notes. You stop at four approval gates, where you decide.

Why the gates matter

One unverified rule in the meeting notes. Choose what happens next.

  1. Meeting notes
  2. Requirement
  3. Gate 1
  4. User story
  5. Backlog item
  6. SQL check
  7. RTM row

Pick a path to see what happens to the rule.

How the course works

You work through eight stages in order. The output of each stage is the input to the next. You use any AI agent that can read a folder: Claude Code, Codex, Cursor, Copilot, opencode, Windsurf or Gemini CLI.

Every item the agent writes is labelled as one of three things. A guess is never presented as a fact.

ConfirmedProposedUnresolved

At each red checkpoint you stop and make a human decision before you continue. The case study is a fictional online-banking address update.

Set up your machine

You need Node.js 20 or later with npm, Python 3, a terminal and an editor such as VS Code. Stages 1, 2, 4, 5, 7 and 8 work with one chat agent and no accounts. Backlog publishing (stage 3) and browser testing (stage 6) need extra connections.

Download the toolkit

Unzip it, open a terminal in the folder, and run the demo data check. It works offline.

unzip ba-automation-toolkit.zip
cd ba-automation-toolkit
python3 tools/init_db.py
python3 tools/run_sql_checks.py

Then open your AI agent in that folder and start at stage 1.

Which agent reads which file

AgentStart in this folderReads rules fromSkills support
Claude CodeclaudeCLAUDE.md.claude/skills/
Codex CLIcodexAGENTS.md.agents/skills/
opencodeopencodeAGENTS.md.agents/skills/
Cursoropen folderAGENTS.md / CLAUDE.mdrules only
VS Code Copilotopen folderAGENTS.md—
Gemini CLIgeminiGEMINI.md (copy of AGENTS.md if needed)—

Requirements elicitation

Turn stakeholder notes into a requirements register where every item cites its source.

Use the ba-requirements skill (if your agent supports skills; otherwise this
prompt is the skill).
Read input/meeting-notes.md and input/scope.md.
Extract objectives, stakeholders, FRs, NFR candidates, API/data candidates,
scope, risks and dependencies.
For every finding, cite the exact source.
Label each item Confirmed, Proposed or Unresolved.
Identify questions requiring stakeholder answers.
Create the files: requirements/requirements-register.md,
requirements/clarification-log.md, validation/requirements-review.md.
No external writes.

User stories & acceptance criteria

Write INVEST stories with Given/When/Then criteria from the reviewed requirements.

Read the reviewed requirements register.
Create epics and INVEST user stories with IDs.
Include linked requirement IDs, user benefit,
Given/When/Then acceptance criteria, positive, negative and boundary
scenarios, dependencies, and a Definition of Ready assessment.
Mark unconfirmed behaviours for stakeholder review.
Save to stories/user-stories.md.

Expected shape: stories/user-stories.sample.md. Criteria remain draft until stakeholders confirm exact business and technical behaviors.

Backlog publication (choose a backend)

Publish the approved stories to a backlog, only after you approve a preview.

Pick one adapter in adapters/ — the prompt below is the same for all:

BackendCostBest when
GitHub IssuesFreeDefault for students — real issue keys, enforced gates
TrelloFreeVisual kanban preference
Google Sheets → NativeTasksFreeBacklog where the team already works
Atlassian Jira/ConfluenceFree sandbox / paid siteEnterprise realism, the guide's default
Read reviewed stories and requirements.
Using the connected backlog tool for my workspace:
find the authorized project/board/sheet.
Show a preview of epic/story titles, acceptance criteria, requirement
mappings and duplicates. Do not write anything yet. Ask for approval.
After approval create only the agreed items.
Return actual issue keys / card IDs / row numbers.
Update the local mappings with verified identifiers.

No connection available → save drafts locally and do not assert publication.

SQL data validation (no agent needed to run)

Check the data with SELECT-only queries. This stage runs without an agent.

python3 tools/init_db.py
python3 tools/run_sql_checks.py
Analyze data/setup.sql and the SQLite database data/banking_demo.db.
Explain table relationships; create a data dictionary and a Mermaid ERD.
Write SELECT-only validation queries. Execute locally if available,
compare actual with expected, and record risks. Never change source records.
Save to data/data-validation.md.

The dataset deliberately contains an orphan audit record and a reconciliation question (customer 101's address). The runner expects: orphan (change_id 5, customer_id 999); counts FAILED=1, PENDING=1, SUCCESS=3. Flag mismatches as questions for confirmation — not as proven production defects.

API requirements

Document the interface without inventing an endpoint.

The meeting notes do not establish a real endpoint. An illustrative JSON shape lives in requirements/api-shape.example.json — it is not a contract.

Read approved FRs and any supplied OpenAPI specification.
Document interface purpose, consumer/provider, methods/endpoints, fields,
authentication, response codes, errors, timeouts, retry/idempotency,
privacy and logging.
Separate Confirmed, Proposed and Unknown.
Never invent a production endpoint or confirmed response.
Save to requirements/api-requirements.md.

UAT generation & Playwright execution

Create the UAT pack, then run it against an approved staging URL only.

Generate the pack with any agent:

Read approved stories, AC and API requirements.
Create a UAT pack with TC ID, mapped requirement, preconditions, test data,
steps, expected result, actual result, status, evidence, defect and owner.
Cover success, invalid/missing input, unauthenticated access, service
failure, duplicate submission and pending updates where applicable.
Mark open rules as Blocked. Save to uat/uat-test-cases.md.

Execution needs an approved staging URL — see SETUP.md for Playwright MCP / browser automation per agent:

Using browser automation against [APPROVED_STAGING_URL] only,
with synthetic test users only. First confirm environment, test credentials,
fixtures and executable cases. Show the plan and request approval.
Once approved: run cases, capture observed behavior and approved evidence,
record Pass/Fail/Blocked/Not Run, and draft defect reports.
Do not run on production or invent evidence.

No staging app → all cases stay Not Run. The public TodoMVC exercise (https://demo.playwright.dev/todomvc) is a connectivity test only.

Traceability matrix (RTM)

Link requirements, stories, tests and evidence, and find the gaps.

Read requirements, stories, API/data requirements, actual issue keys /
card IDs / sheet rows, UAT cases and execution records.
Create traceability/rtm.md.
Include BR, FR, NFR/API/DATA, US, issue key, AC, TC, execution status,
evidence, defect and source.
Find orphan requirements, uncovered tests, broken links, unapproved scope
and unsupported status claims.
Do not manufacture issue keys or evidence.

See traceability/rtm.sample.md for shape and a gap-report example.

Independent quality review

Have a fresh session or a different agent review all of the work.

Run this in a fresh session or a different agent than produced the work:

Act as an independent Senior BA quality reviewer.
Review the original sources and all generated artifacts.
Identify unsupported requirements, missing business rules, contradictions,
scope changes, non-INVEST stories, untestable AC, API assumptions,
incorrect SQL conclusions, missing UAT coverage, broken traceability and
unsupported Pass claims.
For every finding provide ID, severity, exact location, evidence, impact,
corrective action, owner and status.
Mark each artifact Ready / Ready with Conditions / Rework.
Do not change files without approval.

Record results with validation/report-template.md.

The four approval gates

No agent signs off business decisions or test results for you. These are the points where you act.

GateOwner action
1. Requirements baselineValidate scope, source evidence, open rules, priorities
2. PublicationApprove content and destination before any backlog write (GitHub/Trello/Sheets/Jira)
3. Interface / dataConfirm real API contract, data rules, query findings
4. UAT / sign-offApprove staging execution, inspect evidence, review traceability

Rules every agent must follow

These rules are in the toolkit as AGENTS.md and CLAUDE.md, and your agent picks them up automatically.

  1. Never invent requirements or API contracts.
  2. Separate Confirmed, Proposed and Unresolved — never present a guess as a fact.
  3. IDs: BR, FR, NFR, API, DATA, US, TC. Unique, never reused.
  4. Every requirement must cite its source (file + line/quote).
  5. Use INVEST and Given/When/Then for stories.
  6. No writes to external systems (backlog tools, wikis, tickets) without explicit human approval.
  7. No database writes. No UAT against production.
  8. Never invent test results, links or evidence. Unexecuted tests are "Not Run".

Security and operating principles

  • Fictional or explicitly permitted sanitized data only in training.
  • Least-privilege service access; no secrets in prompts or repositories.
  • Human approval before publishing, editing, or consequential actions.
  • Source citations and actual execution evidence for every claim.
  • No agent self-certifies business sign-off or UAT success.