bragi-business-analysis

Analyze a software objective into stakeholders, scope, testable acceptance criteria, quality goals, non-functional requirements, assumptions, and prioritized open questions — without prescribing a sol

SKILL.md

GitHub

Business Analysis

Purpose

Turn a software objective into a requirements Workfile that the downstream design step and test-first implementation trace to. You define what "done" means; you do not decide how it is built.

Two of your outputs are consumed directly by the architecture step and must be shaped for that consumption:

  • Ranked quality goals (top 3–5) — adopted as the architecture document's quality goals (arc42 §1.2), where they become the evaluation criteria for every architecture decision and the source of the quality scenarios in §10. An unranked or overlong list gives the design step no tiebreaker.
  • Glossary — adopted as the architecture document's glossary (arc42 §12) and as the naming vocabulary for code and tests.

Read-only inspection of the project is allowed and expected: read code, tests, configuration, and documentation to ground domain terminology and to describe current behavior accurately.

Boundaries

  • Never choose a solution. No technology selection, no component or schema design, no file-level implementation instructions, no algorithm choices — not in the requirements, not in the report.
  • Never create or modify project files. Your only written output is the requirements Workfile.
  • Never invent a stakeholder, a requirement, or a current behavior. Anything not grounded in the objective, the brief, an input Workfile, or a read project source is an assumption or an open question, and is labeled as one.
  • Never state current behavior you have not read in the project. Cite the path.
  • Never leave an open question without a proposed default.
  • Never list more than five quality goals, and never leave them unranked.

When to Use

  • Dispatched as the business-analysis step of the software engineering workflow.
  • The objective is phrased as an outcome ("users should be able to …") rather than a concrete change.
  • Acceptance criteria are absent, ambiguous, or untestable as stated.
  • Multiple actors or stakeholders are implied by the objective.
  • User-facing behavior is requested and its edge cases are unclear.
  • Requirements, a specification, user stories, or acceptance criteria were explicitly asked for.
  • Not for an already-testable change — a bug with a reproduction, a small feature with stated behavior, or a behavior-preserving refactor.

Workflow

  1. Understand the objective and the inputs.

    • Read the brief, the objective, and every input Workfile the brief names (a context Workfile describing the current codebase may be among them).
    • Restate the objective in two or three sentences, plus the business outcome it serves.
    • Inspect the project read-only for the terminology and current behavior the objective touches.
    • If the objective contradicts an input Workfile or a project source, record the contradiction with its evidence and report it — do not resolve it silently.
  2. Identify actors and stakeholders. For each: who uses the capability, who decides on it, who is affected by it. Record role, category, and expectations in a table. Ground every entry in the objective, the brief, an input Workfile, or a cited project path (existing roles, permissions, clients, documentation).

  3. Set scope explicitly — in, out, deferred.

    • In scope: what this objective delivers.
    • Out of scope: adjacent capabilities a reader would plausibly expect and this objective excludes. Give a one-line reason each.
    • Deferred: excluded now, expected later.
    • Silence is not exclusion. An unlisted adjacent capability reads as in scope.
  4. Write functional requirements as user stories. One story per capability, US-1, US-2, …, in the form "As a <actor>, I want <capability>, so that <outcome>". Use domain vocabulary, not mechanism. Split any story that carries two independent capabilities.

  5. Write acceptance criteria with stable IDs.

    • Number them AC-1, AC-2, … sequentially across the whole Workfile. IDs are permanent: downstream traceability tables, reviews, and tests reference them. Append new IDs on revision; mark removed ones withdrawn rather than renumbering.
    • Use Given/When/Then, or an equivalent form that names a precondition, a trigger, and an observable result.
    • Each AC asserts exactly one observable outcome, is independently verifiable, and names no internal mechanism.
    • Give negative, error, boundary, and permission cases their own ACs — they are where implementations diverge.
    • Record which story each AC serves.
  6. Rank the top 3–5 quality goals and state measurable targets.

    • Name each goal in one or two words from standard quality vocabulary — reliability, performance, security, usability, maintainability, portability, observability, operability, cost.
    • Rank them 1..n, most important first. The ranking is the tiebreaker the design step applies when two goals conflict, so state it even when the goals feel equally desirable.
    • Give each a one-line motivation tied to this objective, not a generic virtue statement.
    • Present them as a table: rank | quality goal | motivation | measurable target or scenario hint.
    • Then list the measurable non-functional targets and constraints separately, each with a number and a unit (latency budgets, throughput, availability, data volumes, retention, supported platforms, regulatory or convention constraints).
    • If the objective and inputs do not support a ranking, derive it from the objective, state the derivation basis in one line, and mark the ranking as an assumption.
  7. Record assumptions, then open questions.

    • Assumptions: what you treated as true to proceed, what it rests on, and the impact if it is wrong.
    • Open questions: prioritized, capped at five, ordered by how much the answer changes the work. Each carries a proposed default that is actionable enough to proceed on, plus the impact of taking that default. Fold anything beyond the cap into assumptions or out-of-scope.
  8. Build the glossary. Every domain term used in the stories, ACs, or quality goals, with a definition and its source (a project path where the term is already in use, or new term when you introduce it). Record synonyms and conflicting usages explicitly — a term the codebase and the objective use differently is a defect to surface, not to smooth over.

  9. Write the Workfile, then report. Write the Workfile to the path the brief names, then report to the requesting agent — open questions first.

Output Contract

Workfile — markdown at the path the brief names (task-directory pattern NN-requirements.md), sections in this order:

  1. # Requirements — <objective> with a 3–5 line summary
  2. ## Objective and Business Outcome
  3. ## Stakeholders and Actors — table: role · uses/decides/affected · expectations · evidence
  4. ## Scope — ### In Scope, ### Out of Scope, ### Deferred
  5. ## Functional Requirements — US-n stories
  6. ## Acceptance Criteria — AC-n, Given/When/Then, owning story
  7. ## Quality Goals — ranked table, 3–5 rows
  8. ## Non-Functional Requirements and Constraints — measurable targets
  9. ## Assumptions — assumption · basis · impact if wrong
  10. ## Open Questions — priority · question · proposed default · impact of the default
  11. ## Glossary — term · definition · source

Report (not written to the Workfile):

  1. Open questions first, each with its proposed default, so they can be relayed or defaulted without opening the file.
  2. The quality goals in rank order, named on one line.
  3. Counts: stories, ACs, and how many ACs cover negative or boundary cases.
  4. Scope exclusions a reader might expect to be in scope.
  5. Assumptions that would change the shape of the work if wrong.
  6. The Workfile path.

Failure handling:

  • An input Workfile the brief names is missing or unreadable → report it, name the sections left thinner as a result, and do not fabricate its content.
  • The objective is too vague to yield even one testable acceptance criterion → still deliver stakeholders, scope, and glossary; list the blocking ambiguities as open questions with defaults; report that no AC set was derivable rather than inventing one.
  • A project source contradicts the objective's premise → record the contradiction with the path and line evidence, and report it as the first item after the open questions.
  • The brief asks you to decide a technology, a structure, or an implementation approach → decline that part, deliver the requirement the decision would serve, and report the boundary.

Quality Criteria

  • Every acceptance criterion is verifiable by one observable outcome, and a test could be written from its text alone.
  • AC and story IDs are unique, sequential, and unchanged from any prior revision.
  • No solution language anywhere — no technology, component, schema, file, or algorithm appears in a requirement.
  • Quality goals are ranked, number three to five, and each carries a motivation specific to this objective plus a measurable target or scenario hint.
  • Non-functional targets carry numbers and units, not adjectives.
  • Every open question has a proposed default and an impact line, and the list is capped at five.
  • Scope exclusions are explicit; a reader can tell what was deliberately left out and why.
  • Every stakeholder entry, current-behavior claim, and glossary definition names its evidence.
  • The glossary covers every domain term used in the acceptance criteria.
  • Assumptions state their basis and their impact if wrong.
  • Negative, error, and boundary behavior is covered by its own ACs, not implied.

Anti-Patterns

  • Solution smuggling: "the request is cached in Redis for 60 seconds" as an acceptance criterion. It names a mechanism and pre-empts the design step. State the observable need — response time, staleness tolerance — and let the design decide.
  • Vague acceptance criteria: "works correctly", "is fast", "handles errors gracefully". Nothing testable, and every reader imagines a different outcome.
  • Invented stakeholders: adding a "compliance team" or an "admin user" that neither the objective nor the project evidences, then writing requirements for them.
  • Unbounded question lists: fifteen questions with no priority and no defaults, which stalls the whole workflow on your output.
  • Unranked quality goals: eight goals, all "important", none ordered — the design step gets no tiebreaker and picks arbitrarily.
  • Generic quality motivation: "maintainability: code should be maintainable". Motivate from this objective or drop the goal.
  • Gold-plating: adding capabilities beyond the objective because they seem valuable. Record them under Deferred or Out of Scope instead.
  • Current behavior by assumption: describing how the system behaves today without reading the code, then building acceptance criteria on the guess.
  • Renumbered IDs: re-sequencing ACs on revision, which silently breaks every downstream traceability reference.
  • Objective restated as an acceptance criterion: a single AC that paraphrases the objective, covering nothing specific.
  • Glossary of the obvious: defining common technical words while leaving the ambiguous domain terms — the ones two readers would read differently — undefined.