Business Analyst harness

GitHub · praxis-ba

The BA harness turns customer language into a typed, versioned requirements canon. It owns requirement states and final product acceptance. It does not write product code.

What you do with it

You bring product intent: a new vision, interview notes, a feature request, changed behavior, or a client bug. The harness helps you preserve the source, ask the missing product questions, split the answer into testable requirements, and prepare one coherent package for architecture.

You are done when another person can open the canon and understand what must be true, why it matters, how it will be accepted, and which decisions still belong downstream.

flowchart TD
  S[Customer source] --> CR[Capture exact request]
  CR --> G[Clarify product choices]
  G --> I[Confirm impact set]
  I --> R[Create or version requirements]
  R --> W[Prepare ready Work Package]
  W --> H[Emit Architect handoff]

Role/stage: ba / research. The source playbook below has a broader tool inventory than the current installed Skills ZIP; source license and ZIP contents are separate questions.

Current Desktop workflow: an existing Jira Epic

Install Runtime and the BA ZIP, then open Jira Epic Analysis. You need the Epic and existing Stories, not the Architect or Developer ZIP. praxis_ba_status inspects canonical and superseded Stories; praxis_ba_preview shows proposed writes. Only praxis_ba_apply with confirmation=YES and the matching previewFingerprint writes Jira.

Inspect Epic PRX-1 and prepare a BA proposal.
Study the requirements and existing Stories first.
Reuse canonical Stories; do not create duplicates or a fourth replacement Story.
Show the preview and wait for confirmation before writing Jira.

After apply, verify canonical Stories and Architect readiness. The next role uses the artifacts without needing your plugin. For existing Stories, see skip repeated BA work.

Advanced local-canon playbook and source tools

The detailed skills, canon scenarios, and CLI examples below are retained from the source-verified local-canon workflow. They were verified against Praxis-mono 4eb831fd44763485ffe17307d366ffebef2f1e12. A current Desktop role ZIP contains Skills, not these source executables. Use a compatible source checkout for CLI recipes, and the current Runtime Skills above for Desktop/Jira operation.

Technical sequence

session-start
  → ba-scaffold or ba-onboard
  → confirm-vision
  → capture-cr → grill-cr → ba-plan-slice
  → human confirm
  → shape-requirement → ba-lint
  → prepare-wp → human plan approval → approve-plan
  → Architect
  → delivered evidence → human accept

Your boundary on the team

Install this harness in the product canon repository. The Business Analyst is the only role that shapes and versions product intent: vision, goals, epics, functional requirements, business rules, non-functional requirements, customer change requests, client-reported bugs, and Work Packages.

The Architect opens the initial WP you prepare in this same product repository and enriches it with technical design while preserving its ID. The Architect reads the handoff you emit. The Developer does not need the BA harness and must not rewrite requirement pages from the code repository.

You receive	You own	You emit
Customer language, research, tickets, feedback	vision.md, cr/, epics/, br/, bugs/, wp/	wp/<WP>/handoffs/ba-architect.handoff.json

Start a BA session with the canon repository as the workspace:

/session-start
I am the Business Analyst. This workspace is the product canon repository.
Report the vision state, open change requests, unresolved client bugs, active
requirements that are not assigned to a Work Package, and the next safe BA action.
Do not perform architecture or implementation work.

New product: vision to the first requirements

Use ba-scaffold for a new product. It creates the surrounding product documentation, shared context, glossary, and NFR catalogue. It does not create the canon. Initialize the release's minimal canon root (.ba/, draft vision.md, and canon folders) before running canon skills; then use confirm-vision to draft or review the vision.

/session-start
Use /ba-scaffold for this new product.

Product and problem: <what exists, for whom, and what is failing today>
Users and value: <primary users and the outcome they need>
Project key: <short stable key>

Create the surrounding product documentation structure and mark unknown facts as
[NEEDS CLARIFICATION]. Do not create canon files as part of /ba-scaffold.
After the canon root is initialized, use /confirm-vision to draft or review
vision.md. Show the objective, scope, non-goals, and candidate measurable goals.
Stop and ask me to confirm the vision.

The vision remains draft until a person confirms it. On confirmation, confirm-vision runs the canonical transaction and validation. Only then can downstream requirements become ready.

Expected result:

vision.md                         status: confirmed
project.md
glossary.md
shared/nfr.md
shared/stakeholders.md
shared/data-model.md

A customer asks for a new feature

Every external request starts as a CR even when the answer looks obvious. capture-cr preserves the customer's exact words; grill-cr separates product decisions from solution design; ba-plan-slice decides how many requirements are needed before IDs are minted.

/capture-cr
Source: <ticket, email, interview, or call reference>
Customer's exact words:
"<paste the request without rewriting it>"

Capture the verbatim request only. Then use /grill-cr one question at a time.
Look up facts in the canon instead of asking me. For each product decision,
recommend an answer and wait for mine. Do not discuss components or code.
Before confirmation, run /ba-plan-slice and show:
- the proposed epic boundary;
- one user story per proposed FR;
- separate reusable BRs and measurable NFRs;
- what is explicitly out of scope;
- the exact spawns/amends impact set.
Stop at the human confirmation gate.

After confirmation:

Realize every confirmed impact with /shape-requirement, one impact at a time.
For new requirements, create draft pages from the canonical templates, write
testable acceptance criteria, activate them through the CLI, and stamp each
spawn back onto the CR. Run /ba-lint and report every unresolved item.

Expected result: cr/CR-###.md is confirmed; each new FR/NFR/BR is active, traces to that CR, and has a realized impact entry.

A change request updates an existing requirement

An existing active or baselined requirement is never edited directly. The confirmed CR must contain an amends: <requirement-id> impact. shape-requirement writes the proposed body to a scratch file and performs the versioned transaction:

praxis-ba req edit --repo <canon-root> --req <requirement-id> \
  --cr <CR-ID> --body-file <scratch-file> --date <YYYYMMDD>
praxis-ba validate --check --repo <canon-root>

The command rejects a no-op, increments version, and preserves the previous body in ## History.

Open <CR-ID> and <requirement-id>. Use /grill-cr to confirm exactly which
observable behavior changes and what remains unchanged. The impact must amend
the existing requirement; do not create a duplicate requirement.

After I confirm the impact set, use /shape-requirement for that amendment.
Draft the complete replacement body in a scratch file, apply the canonical
req edit transaction with the CR and date, then validate. Show me the version
increment, History entry, changed acceptance criteria, and CR trace.

A client reports a bug

capture-bug is for a defect reported against shipped behavior. It is not for a defect discovered by a Developer while implementing the current WP.

/capture-bug
Reporter and date: <who, when>
Affects: <existing requirement ids>
Severity: <severity>
Reproduction: <steps and environment>
Expected: <behavior promised by the canon>
Actual: <observed behavior>

Register this as a client-reported bug and validate the canon. Do not create
a CR automatically. First show whether the fix restores an existing requirement
or changes promised behavior. If it changes behavior, propose spawning a CR and
stop for my decision.

Expected result: bugs/BUG-###.md is open and links the affected requirement. A CR is added only through the explicit bug-resolution path when product behavior must change.

Find unfinished BA work

Ask for read-only status before creating more artifacts:

/status
Show:
1. captured CRs that still need grilling or confirmation;
2. confirmed impacts that have not been realized;
3. active requirements with missing or unverifiable acceptance criteria;
4. active requirements not linked to a Work Package;
5. Work Packages that fail Definition of Ready;
6. open client bugs and their affected requirements.
Do not mutate the canon.

The underlying status flow runs canon status, validation, and the traceability matrix. A missing item is a repair task, not permission to infer product intent.

Prepare the Architect handoff

Group only a coherent, deliverable slice. prepare-wp requires confirmed CRs, active FRs with acceptance criteria, valid traces, and resolved links. The current release also requires an exact wp/<WP-ID>/plan.md before approve-plan, but no BA skill authors that file. Your team must assign its owner and review its contents explicitly; do not describe it as an Architect implementation plan because Architect intake happens after this handoff.

Use /prepare-wp for the smallest coherent slice that delivers <outcome>.
List the confirmed CRs, delivered requirements, and constraints using canonical
relative links. Run the Definition of Ready and link-integrity checks. If any
check fails, stop and tell me which artifact must be repaired.

If ready, stop and report that wp/<WP-ID>/plan.md is required. Do not invent its
owner. Once I identify the owner and the file exists, show its scope and goal and
ask me for explicit approval. Only after I approve, use /approve-plan and emit
wp/<WP-ID>/handoffs/ba-architect.handoff.json.

Do not hand the Architect a chat summary. The JSON contract, WP folder, and linked requirement pages are the durable boundary.

Canon structure and states

.ba/config.yaml
.ba/counters.yaml
vision.md
epics/E#-slug/{index.md,E#-FR#.md,E#-NFR#.md}
br/E#-BR#.md
cr/CR-###.md
wp/WP-YYYYMMDD-NNN/{index.md,plan.md,handoffs/ba-architect.handoff.json}
bugs/BUG-###.md
baselines/BL-YYYYMMDD[-N]/...

• Vision: draft → confirmed.
• Requirements: draft | active | batched | baselined | superseded | retired.
• Change request: captured → confirmed → resolved.
• Work package: draft → ready → plan-approved → accepted, or abandoned.
• Bug: open → fixed | wontfix | duplicate.

Skill reference

Skill	Use when	Reads	Produces	Mutation / gate	Next
session-start	Begin or resume BA work	Repository root, .project, plugin/canon versions	Bootstrap report; missing .project requires acknowledgement	Read-only or advisory; no product mutation	confirm-vision
ba-scaffold	New product has no BA layer	Product brief and target repository layout	Surrounding inputs, shared context, glossary, NFR catalog	Writes the named role artifact; no irreversible transition without its declared gate	Confirm vision or start onboarding
ba-onboard	Code exists but the canon does not	Existing source tree and available product material	Deterministic inventory and first change request	Writes the named role artifact; no irreversible transition without its declared gate	Validate context, then confirm vision
ba-code-surface-scan	Internal operator skill. Onboarding needs raw UI/route evidence	Existing route/UI paths and ignore rules	Read-only surface inventory without product interpretation	Read-only or advisory; no product mutation	Feed the inventory into ba-onboard
confirm-vision	Vision is draft or missing	vision.md and the product owner’s intent	Human-confirmed vision transaction	Writes/updates vision; human confirmation is required	capture-cr
capture-cr	A new request arrives	The request in the user’s original words	Captured request with verbatim and interpreted fields	Writes the named role artifact; no irreversible transition without its declared gate	grill-cr
grill-cr	Scope or intent is unclear	The BA canon, .project, and the active CR or WP	One-question interview and confirmed understanding	Records the interview; human confirms entry point and impacts	ba-plan-slice
ba-plan-slice	Before confirming a CR	The BA canon, .project, and the active CR or WP	Smallest coherent slice and typed impact JSON	Writes a proposal; human chooses or edits it	shape-requirement
shape-requirement	Confirmed impacts are ready	The BA canon, .project, and the active CR or WP	Mint or amend FR, NFR, or BR through canonical operations	Writes the named role artifact; no irreversible transition without its declared gate	ba-lint
ba-lint	After canon writes	The BA canon, .project, and the active CR or WP	Structural and semantic validation	Read-only or advisory; no product mutation	prepare-wp
prepare-wp	Requirements form a deliverable slice	The BA canon, .project, and the active CR or WP	Ready WP with Definition of Ready checks	Writes WP state; human confirms scope and goal	approve-plan
approve-plan	A ready WP has plan.md	The BA canon, .project, and the active CR or WP	Human approval and BA→Architect handoff	Moves the WP and emits handoff only after human approval	accept
accept	Delivery evidence is tied to current HEAD	Delivered IDs, verification evidence, and current git HEAD	Sole baseline writer and final human acceptance	Writes the baseline only after final human acceptance	Close the WP or start the next change
capture-bug	A customer reports a shipped-product defect	A customer-reported shipped-product defect	Canon bug; may spawn a change request	Writes the named role artifact; no irreversible transition without its declared gate	Resolve the bug or spawn a CR
goals	Trace requirements to outcomes	The BA canon, .project, and the active CR or WP	Goal status and missing-link advice	Read-only or advisory; no product mutation	Repair missing links or continue the active WP
one-pager	A stakeholder needs a current product view	The BA canon, .project, and the active CR or WP	Generated page from active canon material	Read-only or advisory; no product mutation	Share the view; return to the canon
status	Inspect the canon	The BA canon, .project, and the active CR or WP	Read-only WP, CR, requirement, and bug diagnostics	Read-only or advisory; no product mutation	Open the reported next action
resume-ba-work	A BA session was interrupted	The BA canon, .project, and the active CR or WP	Next action from canon, artifacts, and pending markers	Read-only or advisory; no product mutation	Continue the persisted transaction
ba-jira-status	Inspect a Jira epic	Configured Jira epic and local canon links	Read-only canonical and superseded issue view	Read-only or advisory; no product mutation	Analyze the epic or return to canon work
jira-analyze-epic	Plan changes for an existing epic	The BA canon, .project, and the active CR or WP	Analysis and write preview; confirmation before apply	Preview first; Jira writes require confirmation	Apply the approved preview
jira-epic-analysis	Use the alternate epic-analysis entry	The BA canon, .project, and the active CR or WP	Same bounded preview/approval workflow	Preview first; Jira writes require confirmation	Apply the approved preview

Human gates

• Vision confirmation is required before dependent work.
• CR confirmation fixes the entry point and exact impact set.
• Plan approval emits the Architect handoff.
• Acceptance binds evidence, current commit, and delivered IDs to a baseline.

The accept transaction writes a pending marker before mutations and removes it last. If a session stops mid-acceptance, resume-ba-work continues the transaction instead of creating another baseline.

CLI operations

The canon CLI has 26 usable paths. See CLI and recovery for the full list.

praxis-ba status --repo <canon-root> --json
praxis-ba validate --repo <canon-root> --check
praxis-ba wp prepare --repo <canon-root> --wp <WP-ID>
praxis-ba wp approve-plan --repo <canon-root> --wp <WP-ID> \
  --plan wp/<WP-ID>/plan.md --json
praxis-ba accept --repo <canon-root> --wp <WP-ID> \
  --evidence <evidence-file> --by <name> --date <date>

baseline is rejected by design. Only accept can write a baseline.

Handoff contract

The BA→Architect JSON includes the contract and version, WP ID and path, delivered FR IDs in requirementIds, visionConfirmed, and readiness checks. NFR and BR constraints remain reachable through the WP scope and closure rather than that array. Architect should refuse intake when readiness is false or the contract is invalid.

Continue with the Architect harness or inspect all handoff fields.