@kudusov.takhir/ba-toolkit 1.2.0

package/skills/analyze/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: ba-analyze
+description: >
+  Cross-artifact quality analysis across all BA Toolkit pipeline artifacts. Use on /analyze command, or when the user asks for "quality check", "analyze artifacts", "find inconsistencies", "cross-artifact check", "check quality", "find duplicates", "terminology check", "coverage analysis", "what is inconsistent". Available at any pipeline stage after /srs. Generates a structured finding report with severity levels.
+---
+
+# /analyze — Cross-Artifact Quality Analysis
+
+Cross-cutting command. Performs a read-only analysis across all existing pipeline artifacts and generates a structured finding report. Does not modify artifacts — use `/clarify` or `/revise` to act on findings.
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it. Use its traceability requirements (section 3) to set CRITICAL/HIGH/MEDIUM thresholds, its Definition of Ready (section 4) to check mandatory fields, its NFR Baseline (section 5) to flag missing categories, and its quality gate (section 6) to determine which severity blocks `/done`.
+1. Read all pipeline artifacts present in the output directory.
+2. Minimum required: `02_srs_*.md`. If only `01_brief_*.md` is available, warn that coverage analysis is limited and proceed with what is available.
+3. Domain reference is not needed — all information comes from the artifacts themselves.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Analysis categories
+
+### 1. Duplication (DUP)
+- Functionally equivalent or near-duplicate FRs within SRS.
+- User stories that describe the same action for the same role.
+- Repeated business rules across multiple artifacts.
+
+### 2. Ambiguity (AMB)
+- Requirements containing metrics-free adjectives: "fast", "reliable", "scalable", "secure", "simple", "efficient" without a measurable criterion.
+- Underspecified scope: "the system" or "the user" without a concrete actor.
+- Conditional requirements without defined conditions.
+
+### 3. Coverage Gap (GAP)
+- FR without at least one linked US.
+- US without linked UC (if Use Cases artifact exists).
+- US without AC (if AC artifact exists).
+- FR without NFR coverage for cross-cutting concerns (security, performance) where domain-expected.
+- Data entities not linked to any FR or US.
+- API endpoints not linked to any FR or US.
+- Wireframes not linked to any US.
+
+### 4. Terminology Drift (TERM)
+- The same concept referred to by different names across artifacts (e.g., "Wallet" in SRS vs "Balance" in Stories vs "Account" in Data Dictionary).
+- Abbreviations expanded differently in different artifacts.
+
+### 5. Invalid Reference (REF)
+- Links to IDs that do not exist (FR-NNN, US-NNN, UC-NNN, etc.).
+- References to roles not defined in the SRS roles section.
+- API endpoint links in wireframes pointing to non-existent endpoints.
+
+## Generation
+
+**File:** `00_analyze_{slug}.md`
+
+```markdown
+# Cross-Artifact Quality Analysis: {Name}
+
+**Date:** {date}
+**Artifacts analyzed:** {list of files found}
+
+## Finding Report
+
+| ID | Category | Severity | Location | Summary | Recommendation |
+|----|----------|----------|----------|---------|----------------|
+| A1 | Duplication | HIGH | srs:FR-003, srs:FR-017 | Both describe user authentication | Merge into a single FR |
+| A2 | Ambiguity | MEDIUM | srs:NFR-002 | "Low latency" has no metric | Add target value in ms |
+| A3 | Coverage Gap | CRITICAL | srs:FR-008 | No linked user story | Create US or remove FR |
+| A4 | Terminology | HIGH | srs, stories | "Wallet" vs "Balance" used interchangeably | Standardize in glossary |
+| A5 | Invalid Ref | CRITICAL | ac:AC-003-01 | Links US-099 which does not exist | Fix reference |
+
+## Coverage Summary
+
+| Artifact pair | Total source | Covered | Uncovered | Coverage % |
+|---------------|-------------|---------|-----------|------------|
+| FR → US | {n} | {n} | {n} | {%} |
+| US → UC | {n} | {n} | {n} | {%} |
+| US → AC | {n} | {n} | {n} | {%} |
+| FR → NFR | {n} | {n} | {n} | {%} |
+| Entity → FR/US | {n} | {n} | {n} | {%} |
+| Endpoint → FR/US | {n} | {n} | {n} | {%} |
+| WF → US | {n} | {n} | {n} | {%} |
+
+_(Rows for artifact pairs where the second artifact has not yet been created are omitted.)_
+
+## Priority Actions
+
+Top 5 highest-severity items to address first, with recommended commands:
+1. {Finding ID} — {summary} → `/clarify FR-NNN` or `/revise [section]`
+```
+
+**Severity scale:**
+- **CRITICAL** — blocks pipeline advancement or handoff (missing mandatory link, non-existent ID).
+- **HIGH** — significant quality risk (duplication, key term drift, missing metric for Must-priority item).
+- **MEDIUM** — quality concern, does not block (missing metric for Should-priority, minor overlap).
+- **LOW** — style or completeness suggestion.
+
+**Rules:**
+- Finding IDs are sequential: A1, A2, ...
+- Each finding references the exact artifact file and element ID.
+- Coverage rows are generated only for artifact pairs where both files exist.
+- The report is read-only — no artifacts are modified.
+
+## Iterative refinement
+
+- `/analyze` again — regenerate after fixes to track progress.
+- `/clarify [FR-NNN or focus]` — resolve specific ambiguities from the report.
+- `/revise [section in artifact]` — fix a specific finding.
+- `/trace` — rebuild the full traceability matrix after fixes.
+
+## Closing message
+
+After saving the report, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Total findings by severity: CRITICAL / HIGH / MEDIUM / LOW.
+- Overall coverage percentage (lowest across all artifact pairs).
+- Top 3 recommended actions with specific commands.
+
+Available commands: `/clarify [focus]` · `/revise [section]` · `/trace` · `/analyze` (re-run after fixes)
+
+No pipeline advancement — this is a quality checkpoint, not a pipeline step.
+
+## Style
+
+Formal, neutral. No emoji, slang. Generate output in the language of the artifacts. Element IDs, file names, and table column headers remain in English.

package/skills/apicontract/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ba-apicontract
+description: >
+  Generate API contracts: endpoints, methods, parameters, request/response schemas, error codes. Markdown format approximating OpenAPI. Use on /apicontract command, or when the user asks for "API contract", "describe API", "endpoints", "REST API", "WebSocket API", "describe API", "integration contract", "swagger", "describe requests and responses", "webhook contract", "API specification". Eighth step of the BA Toolkit pipeline.
+---
+
+# /apicontract — API Contract
+
+Eighth step of the BA Toolkit pipeline. Generates API contracts in Markdown format approximating OpenAPI.
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions (artifact language, ID format, traceability requirements, Definition of Ready, quality gate threshold).
+1. Read `02_srs_*.md`, `03_stories_*.md`, `07_datadict_*.md`. SRS and Data Dictionary are the minimum.
+2. Extract: slug, domain, FR list, entities and attributes, integrations, roles.
+3. If domain supported, load `references/domains/{domain}.md`, section `8. /apicontract`. Use typical endpoint groups.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory for the current platform. If the file is unavailable, apply the default rule: if `/mnt/user-data/outputs/` exists and is writable, save there (Claude.ai); otherwise save to the current working directory.
+
+## Interview
+
+3–7 questions per round, 2–4 rounds.
+
+**Required topics:**
+1. Protocol — REST, WebSocket, GraphQL, combination?
+2. API versioning — URI-based, header-based?
+3. Authentication — JWT, API Key, OAuth2?
+4. Webhook contracts — needed for incoming events from external systems?
+5. Error format — standard (RFC 7807) or custom?
+6. Pagination — cursor-based, offset-based? Limits?
+7. Rate limiting — any restrictions? For which endpoints?
+
+Supplement with domain-specific questions from the reference.
+
+## Generation
+
+**File:** `08_apicontract_{slug}.md`
+
+```markdown
+# API Contract: {Name}
+
+## General Information
+- **Base URL:** {url}
+- **Authentication:** {method}
+- **Versioning:** {strategy}
+- **Data Format:** JSON, UTF-8
+
+## Error Format
+{JSON example}
+
+## Common Error Codes
+| HTTP Code | Error Code | Description |
+
+## Endpoints
+
+### {GROUP}: {Group Name}
+
+#### {METHOD} {/path}
+- **Description:** ...
+- **Linked FR/US:** ...
+- **Authentication:** {required | not required}
+- **Roles:** ...
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+
+**Request Body:** {JSON}
+**Response (200):** {JSON}
+**Error Codes:**
+| Code | Error Code | Condition |
+
+## WebSocket Events (if applicable)
+### Event: {name}
+- **Direction:** {client → server | server → client}
+- **Payload:** {JSON}
+
+## Webhook Contracts (if applicable)
+### Webhook: {name}
+- **Source:** {external system}
+- **Payload:** {JSON}
+```
+
+**Rules:**
+- Endpoints grouped by domain (Auth, Users, Core, Admin, etc.).
+- JSON schemas are representative examples with types in comments.
+- Attributes consistent with Data Dictionary.
+
+## Iterative refinement
+
+- `/revise [endpoint or group]` — rewrite.
+- `/expand [endpoint]` — add parameters, errors, examples.
+- `/clarify [focus]` — targeted ambiguity pass.
+- `/validate` — all FR with interface requirements covered; types match Data Dictionary; HTTP methods correct.
+- `/done` — finalize. Next step: `/wireframes`.
+
+## Closing message
+
+After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Total number of endpoints grouped by HTTP method and domain group.
+- Protocol and authentication method confirmed.
+- WebSocket events and Webhook contracts included (if applicable).
+
+Available commands: `/clarify [focus]` · `/revise [endpoint]` · `/expand [endpoint]` · `/validate` · `/done`
+
+Next step: `/wireframes`
+
+## Style
+
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request. Endpoint names, field names, and error codes remain in English.

package/skills/brief/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: ba-brief
+description: >
+  Generate a high-level Project Brief for projects in any domain (iGaming, Fintech, SaaS, and others). Use this skill when the user enters /brief, or asks to "create a project brief", "describe the project", "start a new project", "project brief", or mentions the starting stage of the analytical pipeline. Also triggers on requests like "begin with a brief", "describe the product", "form a product description". First step of the BA Toolkit pipeline.
+---
+
+# /brief — Project Brief
+
+Starting point of the BA Toolkit pipeline. Generates a structured Project Brief in Markdown. The pipeline is domain-parameterized: the domain is determined at this step and carried through all subsequent skills.
+
+## Loading domain reference
+
+Domain references are located in `references/domains/` relative to the `ba-toolkit` directory. Supported domains: `igaming`, `fintech`, `saas`. For other domains, work without a reference file.
+
+## Workflow
+
+### 1. Environment detection
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory for the current platform. If the file is unavailable, apply the default rule: if `/mnt/user-data/outputs/` exists and is writable, save there (Claude.ai); otherwise save to the current working directory.
+
+### 2. Pipeline check
+
+No prior artifacts required. If `01_brief_*.md` already exists, warn the user and offer to overwrite or create a new project.
+
+If `00_principles_*.md` exists in the output directory, load it and apply its conventions for this and all subsequent pipeline steps (artifact language, ID format, traceability requirements, Definition of Ready, quality gate threshold).
+
+### 3. Domain selection
+
+Ask the user about the project domain. If the domain matches `igaming`, `fintech`, or `saas`, load the corresponding `references/domains/{domain}.md`. Use domain-specific interview questions (section `1. /brief`), typical business goals, risks, and glossary from that file.
+
+If the domain does not match any supported one, record it as `custom:{name}` and use general questions only.
+
+The domain is written into the brief metadata and passed to all subsequent pipeline skills.
+
+### 4. Interview
+
+3–7 questions per round, 2–4 rounds. Do not generate the artifact until sufficient information is collected.
+
+**Required topics (all domains):**
+1. Product type — what exactly is being built?
+2. Business goal — what problem does the product solve?
+3. Target audience and geography.
+4. Key stakeholders — who is interested, who makes decisions?
+5. Known constraints — deadlines, budget, regulatory requirements, mandatory integrations.
+6. Competitive products or references.
+7. Success criteria — specific metrics or qualitative goals.
+
+If a domain reference is loaded, supplement general questions with domain-specific ones. Formulate questions concretely, with example answers in parentheses.
+
+### 5. Generation
+
+**File:** `01_brief_{slug}.md` (slug — kebab-case, fixed here for the entire pipeline).
+
+```markdown
+# Project Brief: {Project Name}
+
+**Domain:** {igaming | fintech | saas | custom:{name}}
+**Date:** {date}
+
+## 1. Project Summary
+## 2. Business Goals and Success Metrics
+## 3. Target Audience
+## 4. High-Level Functionality Overview
+## 5. Stakeholders and Roles
+## 6. Constraints and Assumptions
+## 7. Risks
+## 8. Glossary
+```
+
+### 6. AGENTS.md update
+
+After saving `01_brief_{slug}.md`, create or update `AGENTS.md` in the current working directory (project root). This file helps AI agents in future sessions quickly understand the project context without re-reading all artifacts.
+
+```markdown
+# BA Toolkit — Project Context
+
+**Project:** {Project Name}
+**Slug:** {slug}
+**Domain:** {domain}
+**Language:** {artifact language}
+**Pipeline stage:** Brief complete
+
+## Artifacts
+- `{output_dir}/01_brief_{slug}.md` — Project Brief
+
+## Key context
+- **Business goal:** {one-line summary}
+- **Target audience:** {one-line summary}
+- **Key constraints:** {comma-separated list}
+
+## Next step
+Run `/srs` to generate the Requirements Specification.
+```
+
+If `AGENTS.md` already exists and was created by BA Toolkit, update only the "Pipeline stage" and "Artifacts" sections — do not overwrite custom content added by the user.
+
+### 8. Iterative refinement
+
+- `/revise [section]` — rewrite a section.
+- `/expand [section]` — add detail.
+- `/clarify [focus]` — targeted ambiguity pass.
+- `/validate` — check completeness and consistency.
+- `/done` — finalize and update `AGENTS.md`. Next step: `/srs`.
+
+### 9. Closing message
+
+After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Project name, domain, and slug confirmed for the pipeline.
+- Count of business goals documented and key constraints captured.
+- List of identified risks.
+
+Available commands: `/clarify [focus]` · `/revise [section]` · `/expand [section]` · `/validate` · `/done`
+
+Next step: `/srs`
+
+## Style
+
+Formal, neutral. No emoji, slang, or evaluative language. Terms and abbreviations explained in parentheses on first use. Generate the artifact in the language of the user's request. Section headings, table headers, and labels also in the user's language.

package/skills/clarify/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ba-clarify
+description: >
+  Targeted ambiguity-resolution pass over a BA Toolkit artifact. Use on /clarify command, or when the user asks to "clarify requirements", "find ambiguities", "what is unclear", "check vague terms", "resolve ambiguities", "what needs clarification". Can be focused on a specific area: /clarify security, /clarify FR-012. Cross-cutting command available at any pipeline stage after the first artifact exists.
+---
+
+# /clarify — Targeted Ambiguity Resolution
+
+Cross-cutting command. Performs a post-generation scan of the target artifact, surfaces specific ambiguities as questions, collects answers from the user, and updates the artifact.
+
+## Syntax
+
+```
+/clarify [optional: focus area or element ID]
+```
+
+Examples:
+- `/clarify` — scan the most recent artifact entirely
+- `/clarify security` — focus on security-related requirements
+- `/clarify FR-012` — focus on a single requirement
+- `/clarify NFR` — focus on non-functional requirements
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it. Use its Definition of Ready (section 4) to identify missing mandatory fields, and its ID conventions (section 2) to validate references.
+1. Identify the target artifact:
+   - If the user specifies an element ID (FR-NNN, US-NNN, etc.) or a section keyword, use the artifact that contains it.
+   - Otherwise, use the most recently generated artifact in the output directory.
+2. Read the target artifact fully.
+3. Read prior artifacts for cross-reference checks (roles, terms, IDs).
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory. If unavailable, apply the default rule.
+
+## Analysis pass
+
+Scan the target artifact (or the specified section) for the following ambiguity categories:
+
+### A. Metrics-free adjectives
+Requirements containing words like "fast", "reliable", "scalable", "secure", "user-friendly", "simple", "efficient", "high performance", "low latency" without a measurable criterion.
+
+### B. Undefined terms
+Terms, abbreviations, or roles used in the artifact but not defined in the glossary or SRS roles section.
+
+### C. Conflicting rules
+Business rules or constraints that contradict each other or contradict rules in prior artifacts.
+
+### D. Missing mandatory fields
+Elements that lack required fields per the artifact's own template (e.g., a FR without Priority, a US without Linked FR, an AC without a Then clause).
+
+### E. Ambiguous actors or scope
+Actions assigned to "the system", "the user", or "admin" where the specific role or external system is unclear.
+
+### F. Duplicate or overlapping requirements
+Functionally equivalent or near-duplicate elements within the artifact or across artifacts.
+
+## Output to the user
+
+Present findings as a numbered list of targeted questions. Each item references the exact location (section, element ID, line summary):
+
+```
+Ambiguities found in {artifact_file}:
+
+1. [FR-003] "The system must respond quickly" — what is the acceptable response time in milliseconds under normal load?
+2. [US-007] Role "Manager" is used here but not defined in the SRS Roles section — is this equivalent to "Admin", or a separate role?
+3. [NFR-002 vs FR-015] NFR-002 requires TLS 1.3 only, but FR-015 mentions "standard encryption" — should FR-015 explicitly reference NFR-002?
+4. [AC-005-02] The "Then" clause states "the system handles the error correctly" — what is the specific expected behavior (message shown, state reset, redirect)?
+```
+
+If no ambiguities are found, state that clearly and suggest `/analyze` for a broader cross-artifact check.
+
+## Resolution
+
+After presenting the list, wait for the user to answer. Accept answers inline (user can reply to all questions in one message or answer one by one). After all answers are received:
+
+1. Apply the answers to update the artifact (rewrite affected elements).
+2. If an answer affects a prior artifact (e.g., a role definition belongs in the SRS), flag it and offer to update that artifact as well.
+3. Save the updated artifact.
+
+## Closing message
+
+After saving the updated artifact, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Number of ambiguities found and resolved.
+- Any items deferred (user did not answer or flagged for later).
+- If prior artifacts were also updated, list them.
+
+Available commands: `/clarify [focus]` (run again) · `/validate` · `/done`
+
+No pipeline advancement — return to the current artifact's workflow.
+
+## Style
+
+Formal, neutral. Questions must be specific and reference exact element IDs. Generate output in the language of the artifact.

package/skills/datadict/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ba-datadict
+description: >
+  Generate a Data Dictionary: entities, attributes, types, constraints, relationships. Use on /datadict command, or when the user asks for "data dictionary", "data model", "data schema", "describe entities", "ER model", "database structure", "describe tables", "entity attributes", "entity relationships", "domain model". Seventh step of the BA Toolkit pipeline.
+---
+
+# /datadict — Data Dictionary
+
+Seventh step of the BA Toolkit pipeline. Generates a data dictionary: entities, attributes, data types, constraints, and relationships.
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it and apply its conventions (artifact language, ID format, entity naming convention, Definition of Ready, quality gate threshold).
+1. Read `01_brief_*.md`, `02_srs_*.md`, `03_stories_*.md`. SRS is the minimum requirement.
+2. Extract: slug, domain, entities (mentioned in FR and US), business rules, roles.
+3. If domain supported, load `references/domains/{domain}.md`, section `7. /datadict`. Use mandatory entities and domain-specific questions.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory for the current platform. If the file is unavailable, apply the default rule: if `/mnt/user-data/outputs/` exists and is writable, save there (Claude.ai); otherwise save to the current working directory.
+
+## Interview
+
+3–7 questions per round, 2–4 rounds.
+
+**Required topics:**
+1. DBMS — MongoDB, PostgreSQL, MySQL, other?
+2. Existing schema — is there one to account for or extend?
+3. Audit entities — which require full audit trail?
+4. Soft delete — is soft deletion used?
+5. Amount storage — in minor units (cents) or major currency units?
+6. Versioning — is change history needed for any entities?
+
+Supplement with domain-specific questions and mandatory entities from the reference.
+
+## Generation
+
+**File:** `07_datadict_{slug}.md`
+
+```markdown
+# Data Dictionary: {Name}
+
+## General Information
+- **DBMS:** {type}
+- **Naming Conventions:** {camelCase | snake_case}
+- **Common Fields:** {createdAt, updatedAt, deletedAt}
+
+## Entity: {Name} ({English collection/table name})
+
+**Description:** {purpose in the system.}
+**Linked FR/US:** {references.}
+
+| Attribute | Type | Required | Constraints | Description |
+|-----------|------|----------|-------------|-------------|
+| _id / id | ObjectId / UUID | yes | PK | Unique identifier |
+| {name} | {type} | {yes/no} | {constraints} | {description} |
+
+**Indexes:**
+- {name}: {fields}, {type}
+
+---
+
+## Entity Relationships
+
+| Entity A | Relationship | Entity B | Description |
+|----------|-------------|----------|-------------|
+```
+
+**Rules:**
+- Data types match the chosen DBMS.
+- Constraints include: PK, FK, unique, not null, enum, min/max, regex.
+- Attribute and entity names in English; descriptions in the user's language.
+
+## Iterative refinement
+
+- `/revise [entity]` — rewrite.
+- `/expand [entity]` — add attributes, indexes.
+- `/split [entity]` — separate an entity.
+- `/clarify [focus]` — targeted ambiguity pass.
+- `/validate` — all entities from SRS/stories described; FK references correct; types match DBMS.
+- `/done` — finalize. Next step: `/apicontract`.
+
+## Closing message
+
+After saving the artifact, present the following summary to the user (see `references/closing-message.md` for format):
+
+- Saved file path.
+- Total number of entities documented and total attribute count.
+- DBMS chosen and naming convention confirmed.
+- Entities flagged for audit trail or versioning.
+
+Available commands: `/clarify [focus]` · `/revise [entity]` · `/expand [entity]` · `/split [entity]` · `/validate` · `/done`
+
+Next step: `/apicontract`
+
+## Style
+
+Formal, neutral. No emoji, slang. Terms explained on first use. Generate the artifact in the language of the user's request.

package/skills/estimate/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: ba-estimate
+description: >
+  Effort estimation for BA Toolkit User Stories. Use on /estimate command, or when the user asks to "estimate stories", "add story points", "size the backlog", "estimate effort", "T-shirt sizing", "planning poker". Can target all stories or a specific epic/story. Run after /stories or /ac for best accuracy.
+---
+
+# /estimate — Effort Estimation
+
+Analyses User Stories, assigns effort estimates using the chosen scale, and produces an estimation table with rationale. Can update the stories artifact in-place or output a standalone estimation report.
+
+## Syntax
+
+```
+/estimate [optional: scale] [optional: scope]
+```
+
+Examples:
+- `/estimate` — estimate all stories using Fibonacci Story Points (default)
+- `/estimate t-shirt` — use T-shirt sizes (XS / S / M / L / XL)
+- `/estimate days` — estimate in ideal person-days
+- `/estimate E-01` — estimate only Epic E-01
+- `/estimate US-007` — re-estimate a single story
+
+## Context loading
+
+0. If `00_principles_*.md` exists in the output directory, load it and apply any estimation conventions defined in section 8 (Additional Conventions).
+1. Load `03_stories_{slug}.md` — primary input. Required.
+2. Load `05_ac_{slug}.md` if it exists — AC scenario count per story is a key complexity signal.
+3. Load `02_srs_{slug}.md` — to understand integration points and technical constraints.
+4. Load `07a_research_{slug}.md` if it exists — for ADR-driven complexity signals.
+
+## Environment
+
+Read `references/environment.md` from the `ba-toolkit` directory to determine the output directory.
+
+## Calibration interview
+
+Before estimating, ask the following (skip questions where the answer is already clear from context):
+
+1. **Scale:** Story Points (Fibonacci: 1 / 2 / 3 / 5 / 8 / 13 / 21), T-shirt sizes (XS / S / M / L / XL), or ideal person-days? _(default: Story Points Fibonacci)_
+2. **Reference stories:** Do you have known reference stories to anchor the scale? (e.g. "US-003 is a 3" or "login is an S") If yes, calibrate against those.
+3. **Team assumptions:** Full-stack developer pair? Or separate frontend/backend? _(affects day estimates only)_
+4. **Out of scope for this estimate:** Any stories to skip (e.g., already estimated, on ice)?
+
+If the user types `/estimate` without additional input and prior context is sufficient, proceed with defaults and state assumptions clearly.
+
+## Estimation model
+
+For each User Story, assess the following complexity factors:
+
+| Factor | Signal | Weight |
+|--------|--------|--------|
+| **Scope** | Number of distinct user interactions described | Medium |
+| **AC count** | More scenarios = higher complexity | Medium |
+| **Integration** | External API calls, third-party services, webhooks | High |
+| **UI complexity** | Multi-state screens, real-time updates, complex forms | Medium |
+| **Data complexity** | New entities, complex relationships, migrations | Medium |
+| **Newness** | Team has no prior experience with this area | High |
+| **Uncertainty** | Requirements are unclear or flagged with open questions | High |
+
+Apply the reference stories as anchors. If no references are given, calibrate internally: the simplest story in the set = 1 SP or XS.
+
+Do not pad estimates — model what a reasonably skilled team would take, not a worst-case scenario.
+
+## Output
+
+### If scope ≤ 20 stories — update `03_stories_{slug}.md` in-place
+
+Add a `**Estimate:**` field to each US block and append the Estimation Summary table at the end of the file.
+
+### If scope > 20 stories — create `03_stories_estimates_{slug}.md`
+
+Standalone estimation report with the full table.
+
+---
+
+### Estimation Summary table (always produced in chat as closing output)
+
+```
+## Estimation Summary — [PROJECT_NAME]
+Scale: [Story Points / T-shirt / Days]
+
+| US | Title | Epic | Estimate | Key drivers |
+|----|-------|------|---------|-------------|
+| US-001 | [Title] | E-01 | 3 SP | 2 AC scenarios, simple UI |
+| US-002 | [Title] | E-01 | 8 SP | external payment API, 4 AC scenarios |
+| US-003 | [Title] | E-02 | 13 SP | new domain area, complex state machine |
+...
+
+| Metric | Value |
+|--------|-------|
+| Total stories estimated | [N] |
+| Total Story Points | [N] SP |
+| Largest story | US-[NNN] ([N] SP) — [reason] |
+| Stories ≥ 13 SP (consider splitting) | [N]: US-[NNN], … |
+| Average per story | [N] SP |
+```
+
+### Splitting recommendations
+
+For any story estimated at 13 SP or higher (or XL), suggest a concrete split:
+
+```
+⚠️ US-[NNN] ([N] SP) is large. Consider splitting:
+  → US-[NNN]a: [sub-story suggestion]
+  → US-[NNN]b: [sub-story suggestion]
+Run /split US-[NNN] to perform the split.
+```
+
+## Closing message
+
+After saving, present the following summary (see `references/closing-message.md` for format):
+
+- Saved file path (if stories artifact updated) or new estimate file created.
+- Scale used and total estimate.
+- Number of stories estimated.
+- Stories flagged for splitting (if any).
+- Assumptions made (if defaults were applied without a calibration interview).
+
+Available commands: `/estimate [US-NNN]` (re-estimate a story) · `/split [US-NNN]` (split a large story) · `/analyze` · `/done`
+
+## Style
+
+Be explicit about the rationale for each estimate. Use concise bullet drivers, not paragraphs. Generate output in the language of the artifact.