ai-sdlc-ba

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ai-sdlc-ba: Business Analysis

ai-sdlc-ba：业务分析

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Before producing the final artifact, confirm required inputs, target audience, missing facts, output format, and constraints when they are unclear. Do not invent missing information. Ask concise clarification questions when required inputs are absent.

内部AI SDLC技能，默认不面向客户。以下每条规则都必须遵守，不可跳过任何一条。在生成最终成果前，若所需输入、目标受众、缺失信息、输出格式和约束条件不明确，请先确认这些内容。不得编造缺失信息。当必要输入缺失时，提出简洁的澄清问题。

0. Skill Card

0. 技能卡片

Skill name:
```
ai-sdlc-ba
```
Primary audience: BA
Supporting audience: PM, Dev, QA
Audience tags: BA, PM, Dev, QA
SDLC stage: Business analysis and refinement
Purpose: Convert a vague AI SDLC feature, refactor, or workflow request into requirements-ready business context with actors, rules, assumptions, exclusions, and measurable acceptance criteria.
Output: Business context, rules, assumptions, out-of-scope items, acceptance criteria, and open questions

技能名称：
```
ai-sdlc-ba
```
主要受众：BA
支持受众：PM、Dev、QA
受众标签：BA、PM、Dev、QA
SDLC阶段：业务分析与细化
用途：将模糊的AI SDLC功能、重构或工作流请求转换为可用于需求阶段的业务上下文，包含参与者、规则、假设、排除项和可衡量的验收标准。
输出：业务上下文、规则、假设、范围外事项、验收标准和待解决问题

0.1 Required Inputs

0.1 必要输入

User request or feature/refactor intent.
Business goal, workflow, role, provider, endpoint, or system context.
Existing requirements, product notes, delivery artifact, or
```
specs-refiniment/<feature-name>/<file.md>
```
context if available.

用户请求或功能/重构意图。
业务目标、工作流、角色、提供商、端点或系统上下文。
现有需求、产品说明、交付成果，或可用的
```
specs-refiniment/<feature-name>/<file.md>
```
上下文。

0.2 Clarification Rules

0.2 澄清规则

Ask concise questions before finalizing when role, artifact, requirements, scope, audience, or constraints are unclear.
If optional information is missing, mark it as
```
TBD
```
,
```
Not provided
```
, or
```
Assumption
```
instead of inventing it.
Separate confirmed facts from assumptions and open questions.
Do not proceed to downstream synthesis when a required upstream artifact or decision is missing.

当角色、成果、需求、范围、受众或约束条件不明确时，在最终确定前提出简洁的问题。
若可选信息缺失，标记为
```
TBD
```
、
```
未提供
```
或
```
假设
```
，而非编造信息。
将已确认事实与假设、待解决问题分开。
当必要的上游成果或决策缺失时，不得进行下游合成工作。

0.2.1 Flow Mode Flags

0.2.1 流程模式标志

Support two explicit execution flags:
```
--quick-flow
```
and
```
--full-flow
```
.
If both flags are supplied,
```
--full-flow
```
takes precedence because it is the stricter mode.
```
--quick-flow
```
: move fast, make high-quality progress with available context, avoid clarification questions unless continuing would create material product, security, compliance, data-loss, or irreversible implementation risk.
In
```
--quick-flow
```
, use documented assumptions, recommended defaults, existing repository patterns, and the nearest available artifact evidence; record important assumptions and decisions in
```
decision-log.md
```
.
In
```
--quick-flow
```
, run only focused checks that are directly relevant, cheap, and likely to catch regressions for the requested work; report any skipped broader checks as residual risk.
```
--full-flow
```
: ask concise clarification questions when inputs, scope, ownership, acceptance criteria, or decisions are unclear; do not silently assume material requirements.
In
```
--full-flow
```
, verify upstream and downstream artifacts, decision-log entries, traceability links, acceptance criteria, and validation evidence before finalizing.
In
```
--full-flow
```
, run or recommend the skill-appropriate gates, reviews, scripts, and validation commands needed for end-to-end confidence; document any blocked verification explicitly.
When neither flag is supplied, follow the skill default rules and choose the least risky behavior for the request size and domain.

支持两种明确的执行标志：
```
--quick-flow
```
和
```
--full-flow
```
。
若同时提供两个标志，
```
--full-flow
```
优先，因为它是更严格的模式。
```
--quick-flow
```
：快速推进，利用现有上下文开展高质量工作，除非继续推进会造成重大产品、安全、合规、数据丢失或不可逆的实施风险，否则避免提出澄清问题。
在
```
--quick-flow
```
模式下，使用已记录的假设、推荐默认值、现有仓库模式和最接近的可用成果证据；将重要假设和决策记录在
```
decision-log.md
```
中。
在
```
--quick-flow
```
模式下，仅运行与请求工作直接相关、成本低且可能发现回归问题的针对性检查；将任何跳过的更广泛检查报告为剩余风险。
```
--full-flow
```
：当输入、范围、所有权、验收标准或决策不明确时，提出简洁的澄清问题；不得默认重要需求。
在
```
--full-flow
```
模式下，在最终确定前验证上下游成果、决策日志条目、可追溯链接、验收标准和验证证据。
在
```
--full-flow
```
模式下，运行或推荐技能对应的关卡、评审、脚本和验证命令，以确保端到端的可信度；明确记录任何受阻的验证工作。
当未提供任何标志时，遵循技能默认规则，并根据请求规模和领域选择风险最低的行为。

0.3 Output Rules

0.3 输出规则

Keep output structured with headings and bullets.
Make findings, gaps, risks, and blockers explicit.
Tie recommendations to evidence from the provided artifact,
```
specs-refiniment/<feature-name>/<file.md>
```
workspace, stakeholder context, or user-provided source material.
Include role ownership when the output creates follow-up work for BA, QA, Dev, PM, or Delivery.
Return progress, completion, validation, and handoff summaries directly in the Codex response.

Before the final response, emit the

ai-sdlc-handoff/v1

contract with

result

blockers

next_required

, and

next_optional

; every action includes

reason

command

, and

expected_artifact

Do not create
```
summary.txt
```
,
```
*-summary.txt
```
, or another standalone summary file unless the user explicitly requests one.
Keep durable writes limited to the canonical lifecycle artifacts, decision log, human-readable index, and
```
_ai_sdlc
```
machine files.
Let shared helpers migrate legacy paths on the next write; never overwrite or manually merge divergent legacy and canonical files.

输出需使用标题和项目符号保持结构化。
明确指出发现的问题、缺口、风险和障碍。
建议需与提供的成果、
```
specs-refiniment/<feature-name>/<file.md>
```
工作区、利益相关者上下文或用户提供的源材料中的证据相关联。
若输出为BA、QA、Dev、PM或交付团队产生后续工作，需注明角色所有权。
在Codex响应中直接返回进度、完成情况、验证和交接摘要。

在最终响应前，发出包含

result

、

blockers

、

next_required

和

next_optional

的

ai-sdlc-handoff/v1

契约；每个操作需包含

reason

、

command

和

expected_artifact

。

除非用户明确要求，否则不得创建
```
summary.txt
```
、
```
*-summary.txt
```
或其他独立摘要文件。
持久化写入仅限于标准生命周期成果、决策日志、人类可读索引和
```
_ai_sdlc
```
机器文件。
让共享助手在下次写入时迁移旧路径；不得覆盖或手动合并不一致的旧文件和标准文件。

0.4 Artifact Routing

0.4 成果路由

Maintain a feature decision log whenever this skill records, resolves, changes, or depends on a product, delivery, QA, security, validation, branching, implementation, or rollout decision.
For PM, BA, QA, Delivery, discovery, planning, refinement, and readiness work, write decisions to
```
specs-refiniment/<feature-name>/decision-log.md
```
.
For developer implementation SDD work, write decisions to
```
specs/<feature-name>/decision-log.md
```
.
Each decision-log entry must include date, decision, context or evidence, options considered when relevant, owner, status, and links to affected artifacts, tasks, tests, or validation evidence.

Use this exact decision-log structure:

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

When writing or updating files, place PM, BA, QA, Delivery, discovery, planning, refinement, and readiness artifacts at
```
specs-refiniment/<feature-name>/<file.md>
```
.
Use the path pattern
```
specs-refiniment/<feature-name>/<file.md>
```
; choose a stable feature slug when known, otherwise use
```
tbd-<short-topic>
```
for
```
<feature-name>
```
.
Do not write this skill's output into
```
specs/
```
; that folder is reserved for developer implementation SDD artifacts.
If the user explicitly asks to convert a refined artifact into developer implementation work, hand off to
```
$ai-sdlc-sdd
```
.

每当该技能记录、解决、更改或依赖产品、交付、QA、安全、验证、分支、实施或发布决策时，需维护功能决策日志。
对于PM、BA、QA、交付、探索、规划、细化和准备工作，将决策写入
```
specs-refiniment/<feature-name>/decision-log.md
```
。
对于开发者实施SDD工作，将决策写入
```
specs/<feature-name>/decision-log.md
```
。
每个决策日志条目必须包含日期、决策、上下文或证据、相关备选方案（如有）、负责人、状态，以及受影响成果、任务、测试或验证证据的链接。

使用以下精确的决策日志结构：

markdown

# 决策日志

| ID | 日期 | 状态 | 负责人 | 决策 | 上下文/证据 | 考虑的备选方案 | 受影响成果 | 验证/追溯链接 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | 提议/已接受/已取代/已拒绝 | 角色或姓名 | 简洁决策内容 | 源事实、成果链接或证据 | 选项A；选项B；推荐默认值 | 受影响的文档、任务、代码、测试或发布说明 | 需求ID、测试ID、验证命令、PR、提交记录或工单 |

写入或更新文件时，将PM、BA、QA、交付、探索、规划、细化和准备成果放置在
```
specs-refiniment/<feature-name>/<file.md>
```
路径下。
使用路径模式
```
specs-refiniment/<feature-name>/<file.md>
```
；若已知稳定的功能别名则使用，否则
```
<feature-name>
```
使用
```
tbd-<short-topic>
```
。
不得将该技能的输出写入
```
specs/
```
文件夹；该文件夹专为开发者实施SDD成果保留。
若用户明确要求将细化后的成果转换为开发者实施工作，需交接给
```
$ai-sdlc-sdd
```
。

0.5 Feature State Machine

0.5 功能状态机

Maintain feature lifecycle state in TOON at

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

for refinement work and

specs/<feature-name>/_ai_sdlc/state.toon

for implementation work.

Before executing this skill for a feature, check the state machine with

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

When this skill starts durable work, mark it in progress with
```
begin
```
; when the skill's required artifact or review is complete, mark it done with
```
complete
```
and include
```
--artifacts <path>
```
plus
```
--decision-ref DEC-###
```
when a decision was involved.
In
```
--full-flow
```
, do not proceed when predecessor stages are incomplete, another lifecycle skill is active, or the state file reports a blocker.
In
```
--quick-flow
```
, a predecessor skip is allowed only when continuing is low risk and the command includes
```
--assumption "..."
```
or
```
--decision-ref DEC-###
```
; record the same assumption or decision in
```
decision-log.md
```
.

Use

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

to emit compact LLM-readable state before choosing the next skill.

The state machine is feature-scoped: do not reuse a
```
state.toon
```
across unrelated feature folders.

在TOON中维护功能生命周期状态：细化工作对应

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

，实施工作对应

specs/<feature-name>/_ai_sdlc/state.toon

。

为某个功能执行该技能前，使用

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

检查状态机。

当该技能开始持久化工作时，用
```
begin
```
标记为进行中；当技能所需的成果或评审完成时，用
```
complete
```
标记为已完成，若涉及决策则需添加
```
--artifacts <path>
```
和
```
--decision-ref DEC-###
```
。
在
```
--full-flow
```
模式下，当前置阶段未完成、另一个生命周期技能处于活跃状态或状态文件报告障碍时，不得继续推进。
在
```
--quick-flow
```
模式下，仅当继续推进风险低且命令包含
```
--assumption "..."
```
或
```
--decision-ref DEC-###
```
时，才允许跳过前置阶段；需在
```
decision-log.md
```
中记录相同的假设或决策。

在选择下一个技能前，使用

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

生成紧凑的LLM可读状态。

状态机以功能为范围：不得在不相关的功能文件夹间复用
```
state.toon
```
。

0.6 Artifact Metadata And Metatags

0.6 成果元数据与元标签

Every Markdown artifact generated or updated by this skill must start with an
```
artifact_metadata
```
YAML frontmatter block before the first visible heading.

Use schema

ai-sdlc-artifact-metadata/v1

and keep these fields current:

feature

artifact

path

workspace

skill

flow_mode

state_file

decision_log

status

owner

created_at

updated_at

trace_ids

related_artifacts

validation

, and

metatags

```
metatags
```
must include at minimum
```
ai-sdlc
```
, the workspace (
```
refinement
```
or
```
implementation
```
), this skill name, the artifact type or filename stem, and a lifecycle/status tag such as
```
draft
```
,
```
review
```
,
```
approved
```
, or
```
validated
```
.
When
```
--quick-flow
```
is active, set
```
flow_mode: quick
```
, keep assumptions visible in the body, and add tags for major defaults or unresolved risk only when they help retrieval.
When
```
--full-flow
```
is active, set
```
flow_mode: full
```
, keep blockers and validation evidence reflected in
```
status
```
,
```
validation
```
,
```
trace_ids
```
, and
```
related_artifacts
```
.
Update metadata whenever the artifact path, status, owner, trace links, validation evidence, related artifacts, or decision references change.
Metadata is an index for routing, retrieval, and traceability; it does not replace the artifact body,
```
decision-log.md
```
, or
```
state.toon
```
.

该技能生成或更新的每个Markdown成果，必须在第一个可见标题前包含
```
artifact_metadata
```
YAML前置块。

使用

ai-sdlc-artifact-metadata/v1

schema，并保持以下字段最新：

feature

、

artifact

、

path

、

workspace

、

skill

、

flow_mode

、

state_file

、

decision_log

、

status

、

owner

、

created_at

、

updated_at

、

trace_ids

、

related_artifacts

、

validation

和

metatags

。

```
metatags
```
至少必须包含
```
ai-sdlc
```
、工作区（
```
refinement
```
或
```
implementation
```
）、该技能名称、成果类型或文件名主干，以及生命周期/状态标签（如
```
draft
```
、
```
review
```
、
```
approved
```
或
```
validated
```
）。
当
```
--quick-flow
```
模式激活时，设置
```
flow_mode: quick
```
，在正文中显示假设，仅当有助于检索时才添加主要默认值或未解决风险的标签。
当
```
--full-flow
```
模式激活时，设置
```
flow_mode: full
```
，在
```
status
```
、
```
validation
```
、
```
trace_ids
```
和
```
related_artifacts
```
中反映障碍和验证证据。
每当成果路径、状态、负责人、追溯链接、验证证据、相关成果或决策引用发生变化时，更新元数据。
元数据是用于路由、检索和可追溯性的索引；它不能替代成果正文、
```
decision-log.md
```
或
```
state.toon
```
。

0.7 Specs Index

0.7 规格索引

Before searching across feature folders, inspect the compact LLM index first:
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
for refinement work or
```
specs/_ai_sdlc/specs-index.toon
```
for implementation work.
Use the human-readable index at
```
specs-refiniment/specs-index.md
```
or
```
specs/specs-index.md
```
when reporting feature coverage, artifact inventory, or handoff status to people.

After this skill creates or materially updates an artifact, refresh the matching workspace index with

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

In
```
--quick-flow
```
, rely on
```
specs-index.toon
```
to choose the smallest relevant artifact set before opening files.
In
```
--full-flow
```
, verify the updated artifact appears in both
```
specs-index.toon
```
and
```
specs-index.md
```
before final handoff.
The specs index summarizes artifact metadata and state; it does not replace reading the selected source artifacts when details, approvals, or validation evidence matter.

在跨功能文件夹搜索前，先查看紧凑的LLM索引：细化工作对应
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
，实施工作对应
```
specs/_ai_sdlc/specs-index.toon
```
。
向人员报告功能覆盖范围、成果清单或交接状态时，使用人类可读的索引
```
specs-refiniment/specs-index.md
```
或
```
specs/specs-index.md
```
。

该技能创建或大幅更新成果后，使用

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

刷新匹配的工作区索引。

在
```
--quick-flow
```
模式下，依赖
```
specs-index.toon
```
选择最小的相关成果集，再打开文件。
在
```
--full-flow
```
模式下，在最终交接前验证更新后的成果是否出现在
```
specs-index.toon
```
和
```
specs-index.md
```
中。
规格索引汇总成果元数据和状态；当细节、审批或验证证据很重要时，它不能替代读取选定的源成果。

0.8 Complete Refinement Cascade

0.8 完整细化流程

Trigger the complete cascade only when the user explicitly asks for a full, complete, or end-to-end spec refinement or asks for every refinement artifact. A normal
```
--full-flow
```
call for one skill remains single-stage.
Before the first durable write, run
```
python3 skills/_shared/refinement_status.py --feature <feature-name> --gate full --format toon
```
and start with the earliest reported
```
next_skill
```
, including stages earlier than this skill.
Execute the existing refinement skills in lifecycle order with
```
--full-flow
```
: discovery, PRFAQ, delivery-package gap review, requirements readiness, goal/capability mapping, backlog gap review, backlog decomposition, story decomposition, release slicing, BA context, delivery spec, QA plan, QA gap review, test strategy, test cases, test suite, QA readiness, and delivery handoff.
Produce all 18 canonical Markdown artifacts.
```
release-slicing.md
```
is mandatory for a complete cascade; when release slicing is not applicable, write an explicit evidence-backed N/A artifact and complete the stage instead of skipping it.
After every stage, finalize its artifact, record required decisions, mark the stage
```
done
```
, and refresh the refinement indexes before selecting the next skill.
Do not declare the cascade complete until
```
python3 skills/_shared/refinement_status.py --feature <feature-name> --gate full --format markdown
```
exits successfully with
```
18/18
```
. If it fails, continue with the reported next skill or return the concrete blocker and remaining inventory in Codex.
Surface checkpoint and final summaries in Codex only; never persist a cascade summary as a text file.

仅当用户明确要求完整的或端到端的规格细化，或要求所有细化成果时，才触发完整流程。普通的
```
--full-flow
```
调用单个技能仍为单阶段。

在首次持久化写入前，运行

python3 skills/_shared/refinement_status.py --feature <feature-name> --gate full --format toon

，并从报告的最早

next_skill

开始，包括早于该技能的阶段。

按生命周期顺序使用
```
--full-flow
```
执行现有细化技能：探索、PRFAQ、交付包缺口评审、需求就绪、目标/能力映射、待办事项缺口评审、待办事项分解、用户故事分解、发布切片、BA上下文、交付规格、QA计划、QA缺口评审、测试策略、测试用例、测试套件、QA就绪和交付交接。
生成所有18个标准Markdown成果。
```
release-slicing.md
```
是完整流程的必填项；当发布切片不适用时，需写入一个明确的、有证据支持的N/A成果并完成该阶段，而非跳过。
每个阶段完成后，最终确定其成果、记录必要的决策、将阶段标记为
```
done
```
，并在选择下一个技能前刷新细化索引。
仅当
```
python3 skills/_shared/refinement_status.py --feature <feature-name> --gate full --format markdown
```
成功退出且显示
```
18/18
```
时，才宣布流程完成。若失败，则继续执行报告的下一个技能，或在Codex中返回具体障碍和剩余任务清单。
仅在Codex中显示检查点和最终摘要；不得将流程摘要保存为文本文件。

References

参考资料

Use
```
scripts/ba_context_scaffold.py
```
when deterministic scaffolding, planning, or formatting is useful for this workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill.
Read
```
references/business-context-template.md
```
when the task needs the detailed structure, checklist, or examples for this skill.

当该工作流需要确定性脚手架、规划或格式化时，使用
```
scripts/ba_context_scaffold.py
```
；传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
当任务需要该技能的详细结构、检查清单或示例时，阅读
```
references/business-context-template.md
```
。

Script Usage

脚本用法

In default and full flow, always run this skill's primary analysis script with
```
--format toon --budget-tokens 24000
```
before drafting; explicit inputs are priority evidence but do not replace the rest of the feature package.
Read this skill's reference file before writing sections. Use its detailed tables and quality bar, not only the compact scaffold headings.
Run the primary script with
```
--emit-template
```
in the active flow mode to obtain the exact shared context headings and required stage table columns before section writes.
Make every default/full artifact self-contained by completing all ten shared feature-context sections plus the stage-specific profile sections. Quick flow may use the compact stage-only draft.
Follow every
```
next_reads
```
entry before finalization and list every consumed source in
```
Source Coverage
```
; do not claim whole-feature context from a partial source set.
Keep the final artifact within
```
--max-artifact-tokens 24000
```
; condense repetition instead of dropping feature dimensions or source traceability.
Run
```
scripts/ba_context_scaffold.py
```
before drafting or updating this skill's artifact when inputs are longer than a few bullets, when traceability matters, or when a flow flag is supplied. For agent analysis, pass
```
--format toon
```
, read
```
anchors
```
first, and open only
```
next_reads
```
; without that flag the script keeps its human-readable Markdown output.

Quick flow analysis:

python3 skills/ai-sdlc-ba/scripts/ba_context_scaffold.py --feature <feature-name> --quick-flow <input.md>...

Full flow analysis:

python3 skills/ai-sdlc-ba/scripts/ba_context_scaffold.py --feature <feature-name> --full-flow <input.md>...

To write content, pass one canonical heading with
```
--section "<section>"
```
; provide only that section body on stdin, without H1, H2, frontmatter, or a temporary content file.
Repeat
```
--section
```
for each required section, then run the same script with
```
--finalize
```
to validate the artifact and refresh metadata and specs indexes.
The AI must not write or directly edit the routed Markdown artifact; the script owns scaffold creation, section placement, and durable file writes.
Use
```
--decision-row
```
with one nine-cell Markdown table row on stdin when a decision-log entry is required.

Legacy

--emit-template

--emit-decision-log-entry

, and

--write

remain available for compatibility.

Use
```
--quick-flow
```
for first-pass synthesis with assumptions; use
```
--full-flow
```
before readiness, handoff, signoff, or any decision-sensitive output.

在默认和完整流程中，起草前始终运行该技能的主要分析脚本，参数为
```
--format toon --budget-tokens 24000
```
；明确输入是优先证据，但不能替代其余功能包内容。
编写章节前阅读该技能的参考文件。使用其详细表格和质量标准，而非仅使用紧凑的脚手架标题。
在当前流程模式下运行主脚本并添加
```
--emit-template
```
参数，以获取精确的共享上下文标题和所需阶段表格列，再进行章节编写。
每个默认/完整成果必须包含所有十个共享功能上下文章节以及阶段特定的概要章节。快速流程可使用紧凑的仅阶段草稿。
最终确定前遵循每个
```
next_reads
```
条目，并在
```
Source Coverage
```
中列出所有使用的源；不得从部分源集声称拥有完整功能上下文。
最终成果需控制在
```
--max-artifact-tokens 24000
```
范围内；浓缩重复内容，而非省略功能维度或源追溯性。
当输入超过几个项目符号、追溯性很重要或提供了流程标志时，起草或更新该技能的成果前运行
```
scripts/ba_context_scaffold.py
```
。对于代理分析，传递
```
--format toon
```
参数，先读取
```
anchors
```
，再打开仅
```
next_reads
```
；若无该标志，脚本将保持人类可读的Markdown输出。

快速流程分析：

python3 skills/ai-sdlc-ba/scripts/ba_context_scaffold.py --feature <feature-name> --quick-flow <input.md>...

完整流程分析：

python3 skills/ai-sdlc-ba/scripts/ba_context_scaffold.py --feature <feature-name> --full-flow <input.md>...

要编写内容，传递一个标准标题并添加
```
--section "<section>"
```
参数；仅在标准输入中提供该章节正文，无需H1、H2、前置内容或临时内容文件。
对每个所需章节重复
```
--section
```
参数，然后运行相同的脚本并添加
```
--finalize
```
参数，以验证成果并刷新元数据和规格索引。
AI不得直接写入或编辑路由的Markdown成果；脚本负责脚手架创建、章节放置和持久化文件写入。
当需要决策日志条目时，使用
```
--decision-row
```
参数，并在标准输入中提供一行九单元格的Markdown表格。

旧版参数

--emit-template

、

--emit-decision-log-entry

和

--write

仍可兼容使用。

使用
```
--quick-flow
```
进行带假设的首次合成；在就绪、交接、签字或任何决策敏感输出前使用
```
--full-flow
```
。

Purpose

用途

Convert a vague AI SDLC feature, refactor, or workflow request into requirements-ready business context with actors, rules, assumptions, exclusions, and measurable acceptance criteria.

将模糊的AI SDLC功能、重构或工作流请求转换为可用于需求阶段的业务上下文，包含参与者、规则、假设、排除项和可衡量的验收标准。

Inputs

输入

Collect the user request and any explicit business goal, pain point, asset, provider, endpoint, role, or workflow name.
Read the matching requirements document, delivery artifact, or
```
specs-refiniment/<feature-name>/<file.md>
```
package when one exists.
Read
```
references/business-context-template.md
```
when the request needs a reusable intake structure.
Collect current behavior from code or docs only when the desired business behavior depends on existing workflow semantics.

收集用户请求以及任何明确的业务目标、痛点、资产、提供商、端点、角色或工作流名称。
若存在匹配的需求文档、交付成果或
```
specs-refiniment/<feature-name>/<file.md>
```
包，需读取。
当请求需要可复用的接收结构时，阅读
```
references/business-context-template.md
```
。
仅当所需业务行为依赖现有工作流语义时，从代码或文档中收集当前行为。

Steps

步骤

State the business goal in one sentence.
State the problem in one sentence that names the current failure, missing capability, or decision gap.
List actors and systems that initiate, approve, observe, or are affected by the change.
Describe current behavior and desired behavior as separate bullets.
Extract business rules using deterministic language:
```
When X, the system must Y
```
.
List assumptions separately from confirmed facts.
List out-of-scope items so implementation does not expand silently.
Write acceptance criteria as observable pass/fail statements.
Write open questions only for decisions that materially affect scope, design, validation, or rollout.
Return requirements-ready BA notes and write them under
```
specs-refiniment/<feature-name>/<file.md>
```
when file output is requested.

用一句话陈述业务目标。
用一句话陈述问题，指出当前的故障、缺失的能力或决策缺口。
列出发起、批准、观察或受变更影响的参与者和系统。
将当前行为和期望行为分列为项目符号。
使用确定性语言提取业务规则：
```
当X发生时，系统必须执行Y
```
。
将假设与已确认事实分开列出。
列出范围外事项，避免实施范围无限制扩大。
将验收标准写为可观察的通过/失败陈述。
仅针对对范围、设计、验证或发布有重大影响的决策，写入待解决问题。
返回可用于需求阶段的BA笔记；若要求文件输出，将其写入
```
specs-refiniment/<feature-name>/<file.md>
```
。

Output Spec

输出规格

Use this format for visible BA output or requirements-ready notes:

text

Business context:
- Goal: one sentence.
- Problem: one sentence.
- Actors: actor list.
- Current behavior: concrete observed behavior.
- Desired behavior: concrete target behavior.

Rules and constraints:
- Rule: When condition, the system must outcome.
- Constraint: limit, dependency, policy, or compatibility requirement.
- Assumption: unverified statement that must be validated or accepted.
- Out of scope: explicit exclusion.

Acceptance criteria:
- AC-001: Given setup, when action, then observable result.

Open questions:
- Question: decision needed, why it matters, owner if known.

Quality gate:

Pass when BA, PM, QA, and Dev stakeholders can use the output without guessing actors, expected outcomes, exclusions, or acceptance criteria.
Fail when the output contains vague goals such as "make it better", acceptance criteria without observable results, or assumptions mixed into facts.

可见BA输出或可用于需求阶段的笔记使用以下格式：

text

业务上下文：
- 目标：一句话。
- 问题：一句话。
- 参与者：参与者列表。
- 当前行为：具体的观察行为。
- 期望行为：具体的目标行为。

规则与约束：
- 规则：当[条件]时，系统必须[结果]。
- 约束：限制、依赖、政策或兼容性要求。
- 假设：未经验证的陈述，必须验证或接受。
- 范围外：明确的排除项。

验收标准：
- AC-001：给定[设置]，当执行[操作]时，会出现[可观察结果]。

待解决问题：
- 问题：所需决策、重要性、已知负责人（如有）。

质量关卡：

通过：BA、PM、QA和Dev利益相关者无需猜测参与者、预期结果、排除项或验收标准即可使用输出。
失败：输出包含模糊目标（如“使其更好”）、无观察结果的验收标准，或假设与事实混合。

Examples

示例

Before:

text

Add better BitGo wallet support.

After:

text

Business context:
- Goal: Let operations view BitGo enterprise wallet details before initiating transfers.
- Problem: Operators cannot verify wallet scope and enterprise linkage from the current setup screen.
- Actors: operations user, BitGo integration, AI SDLC API.
- Current behavior: The UI shows configured provider status without wallet-level enterprise details.
- Desired behavior: The UI shows enterprise-linked wallet details required for transfer readiness review.

Acceptance criteria:
- AC-001: Given an organization with BitGo configured, when an operations user opens custodian setup, then the response includes enterprise ID, wallet IDs, and display labels.

Invalid counter-example:

text

Acceptance criteria:
- Works correctly.

Reject this because it has no actor, trigger, or observable result.

转换前：

textAdd

undefined

转换后：

text

业务上下文：
- 目标：让操作人员在发起转账前查看BitGo企业钱包详情。
- 问题：操作人员无法从当前设置屏幕验证钱包范围和企业关联。
- 参与者：操作人员、BitGo集成、AI SDLC API。
- 当前行为：UI显示已配置的提供商状态，但无钱包级别的企业详情。
- 期望行为：UI显示转账就绪审核所需的企业关联钱包详情。

验收标准：
- AC-001：给定已配置BitGo的组织，当操作人员打开托管设置时，响应包含企业ID、钱包ID和显示标签。

无效反例：

text

验收标准：
- 正常工作。

拒绝该示例，因为它没有参与者、触发条件或可观察结果。

Edge Cases

边缘情况

Stop before implementation when acceptance criteria would require inventing product policy.
Mark unknowns as assumptions or open questions; do not hide them inside requirements.
Use
```
TODO(dm): exact question
```
in specs when a delivery-manager decision is required.
Keep BA output out of solution architecture unless a business rule constrains design.
Use
```
$ai-sdlc-sdd
```
after BA to update requirements, design, test cases, QA, and tasks.

当验收标准需要编造产品政策时，在实施前停止。
将未知项标记为假设或待解决问题；不得隐藏在需求中。
当需要交付经理决策时，在规格中使用
```
TODO(dm): exact question
```
。
除非业务规则限制设计，否则BA输出不得涉及解决方案架构。
BA完成后使用
```
$ai-sdlc-sdd
```
更新需求、设计、测试用例、QA和任务。

Scope Boundary

范围边界

Do not design APIs, schemas, data models, or package boundaries; use
```
$ai-sdlc-sdd
```
and architecture guidance for design.
Do not write implementation tasks except when translating accepted BA output into requirements context.
Do not claim assumptions are confirmed without evidence from the user, artifact,
```
specs-refiniment/<feature-name>/<file.md>
```
, code, or docs.

不得设计API、 schema、数据模型或包边界；设计需使用
```
$ai-sdlc-sdd
```
和架构指南。
不得编写实施任务，除非将已接受的BA输出转换为需求上下文。
若无用户、成果、
```
specs-refiniment/<feature-name>/<file.md>
```
、代码或文档的证据，不得声称假设已确认。