SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsaile-requirement-analysis

aile-requirement-analysis

Office & productivity

View repository

Updated 10-16 08:01

About this skill

Aile: Requirement intake (aile-requirement-analysis)

Source original Skill

  • Source: superpowers requirement clarification capability (migrated to aile-only)
  • Strategy: retain the "single-question progression + structured analysis" process, and enhance the Jira Story intake contract.

Overview

This skill is used for the first step of Phase 2: converting the input of a Jira Story (requirement description, UI mockups, constraints) into structured material usable for planning and design.

Boundary constraints:

  • This skill is only responsible for analysis, clarification, and structured output, and produces/updates docs/plans/{Story-Key}/analysis.md
  • This skilldoes not modify business code, test code, specification documents, or module documents
  • This skill only records "archive system backfill suggestions"; the actual backfill action must be left to aile-writing-plans / aile-executing-plans phase
  • This skill by defaultdoes not create Jira Sub-task
  • If it is determined that subtasks may need to be split later, suggestions can only be given in the analysis results, and the user should be prompted to decide whether to enter aile-writing-plans
  • If the current Jira ticket belongs to the "missing / gap / small-scope patch / defect fix" type, the analysis phaseforbidscreating subtasks, and only outputs analysis conclusions and suggestions

Workflow overview

项目初始化：project-docs-init（创建文档）
      ↓
需求分析：aile-requirement-analysis（结构化需求分析 + 产出 analysis.md）
      ↓
计划制定：aile-writing-plans（设计 + 计划）
      ↓
执行开发：aile-executing-plans 或 aile-subagent-dev（按计划执行 + 人工检查点）
      ↓
交付总结：aile-delivery-report（整理交付材料 + 回链 Story）

Skill process

Understand this idea:

  • First check the current project status (documents, files, recent commits)
  • Ask one question at a time to refine the idea
  • Prefer multiple-choice questions when possible, but open-ended questions are also acceptable
  • Only one question per message - if a topic needs more exploration, break it down into multiple questions
  • Focus on understanding: purpose, constraints, success criteria

Exploration methods:

  • Propose 2-3 different approaches with trade-offs
  • Present options along with your recommendations and reasoning in a conversational manner
  • Start with your recommended option and explain why

Present the design:

  • Once you believe you understand what you are building, you can present the design
  • Break it into 200-300 word sections
  • After each section, ask whether it looks correct so far
  • Cover: architecture, components, data flow, error handling, testing
  • If something does not make sense, be prepared to go back and clarify

After Skill design

Documents:

  • Write the validated analysis results into docs/plans/{Story-Key}/analysis.md
  • If possible, use style elements: clear and concise writing techniques
  • Do not commit git unless the user explicitly requests it

Implementation (if continuing):

  • Ask: "Ready to implement?"
  • Use superpowers: aile-writing-plans to create a detailed implementation plan

Skill key principles

  • One question at a time - do not overwhelm with multiple questions
  • Prefer multiple choice - easier to answer than open-ended when possible
  • Ruthless YAGNI - remove unnecessary features from all designs
  • Explore alternatives - Always propose 2-3 approaches before solving
  • Incremental validation - Present the design in parts, validate each part
  • Stay flexible - Go back and clarify when something doesn't make sense

Input

  • Jira Story: Description, Acceptance Criteria (if any), attachments/links (UI mockups) - (Optional) related Epic / dependent Story - (Optional) related spec/module document paths (only used to determine whether a documentation system backfill is needed later)

Core output contract (must be followed)

  1. The plan file must be located at:docs/plans/{Story-Key}/analysis.md
  2. The file must contain:
    • Requirement understanding and risks
    • User paths/core interactions
    • Draft Acceptance Criteria (AC): rewrite business statements into testable items
    • Implicit requirements list (e.g., permissions, empty states, error states, performance/compatibility)
    • Documentation system backfill suggestions: only record the documents suggested for backfill, the reasons, and the priority; do not execute the backfill
    • Suggested Phase 2 next steps: whether Pencil design is needed, whether splitting into subtasks later is recommended
    • Subtask decision record:默认不创建 / 用户已明确要求创建 / 缺失类单据禁止创建
  3. analysis.md Must explicitly state:
    • Whether a documentation system backfill is recommended later: Yes/No
    • Suggested file paths or document domains for backfill (e.g., docs/specs/PRD.md、docs/modules/payment.md）
    • Backfill reason and scope of impact
    • Which subsequent planned task is suggested for execution
  4. This skill must not directly modify any docs/specs/*、docs/modules/*、docs/guides/* or other documentation files
  5. This skill must not perform Google Drive sync or other documentation archiving actions
  6. If the user explicitly requests preparation of a Jira Comment, a ADF（Atlassian Document Format） draft must first be generated; if the current toolchain does not support direct ADF submission, automatic backfill is prohibited, and it degrades to "output ADF content + prompt for manual submission"

Subtask boundaries (must be followed)

  1. aile-requirement-analysis phaseProhibitedCreate Jira Sub-task
  2. The responsibility for creating subtasks belongs to aile-writing-plans, not this skill
  3. For "missing / gap / patch / small fix" type Jira issues:
    • Only perform analysis
    • Do not split into subtasks
    • Do not prompt for automatic creation
  4. For complex requirements, if after analysis it is determined that "subtasks may need to be split later":
    • Can only output "suggested to create later in the aile-writing-plans phase"
    • Must prompt the user for confirmation
    • The default answer isdo not create
  5. Without explicit user authorization, no jira_create_issue / jira_batch_create_issues capability may be invoked

Jira issue type determination (used for subtask suggestions)

Prioritize the following signals to determine whether it is a "missing-type issue":

  • Issue Type / labels / custom fields explicitly marked as:缺失、gap、bugfix、补漏、修补
  • The title or description presents the semantics of "patch a gap / fix a missing item / complete omitted logic"
  • Single-point impact scope, clear boundaries, no need for multi-role parallel progress

If any of the above conditions is met:

  • Write the conclusion as:本单归类为缺失类单据
  • Write the subtask suggestion as:否
  • Write the reason as:分析阶段仅输出结论与风险，禁止建立子任务

Jira MCP (optional)

If the environment provides a Jira MCP Tool (for example mcp-atlassian), execute the following steps:

  1. Read the Story:jira_get_issue
  2. First generate the of the "requirement intake summary"
  3. If the current toolchain supports submitting an ADF Comment: then perform the Jira write-back
  4. If the current toolchain only supports Markdown Comments: automatic write-back is prohibited; instead, attach the ADF content in analysis.md and prompt for manual submission

Note: credentials (API Token) must be injected via environment variables and must not be written into the repository.

Jira Comment write-back format (mandatory)

If the requirement intake result is to be written back to Jira, it must first be organized into an ADF structure, containing at least:

{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "[G1] 需求接入摘要" }]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "需求摘要：..." }]
            }
          ]
        }
      ]
    }
  ]
}

Blocks that must be included at minimum:

  • Requirement summary
  • Risks and implicit requirements
  • Specification backfill assessment
  • Subtask suggestions and decisions
  • Questions to be confirmed

Prohibitions:

  • It is prohibited to directly treat plain Markdown text as "ADF format" and claim that write-back has been completed
  • It is prohibited to call automatic write-back and report success without confirming that the tool supports ADF

Archive system backfill suggestions (must be followed)

If, after analysis, it is determined that the archive system needs to be updated later (such as docs/specs/*、docs/modules/*、docs/guides/*）：

  1. Only in analysis.md record "suggested backfill"
  2. Must specify the suggested backfill files, reasons, impact scope, and priority
  3. Must clearly state:本阶段不执行回补，由 aile-writing-plans 转成执行任务
  4. Must not directly modify documents, sync to the cloud, or trigger any archiving process at this stage

Execution flow

  1. Obtain the Story Key
  2. Read and restate the requirement (to avoid misunderstanding)
  3. Determine the ticket type: whether it belongs to the "missing / gap / omission / patch" category
  4. List uncertainties (one question at a time, prefer multiple-choice)
  5. Produce a structured summary and the analysis.md analysis file (refer to docs-templates/stage2-analysis-template.md）
  6. Output the "archive system backfill suggestion" (whether backfill is recommended + backfill file list + reasons)
  7. Output "subtask suggestions and decisions":
    • Default:不创建
    • Missing-type tickets:禁止创建
    • If a complex requirement needs to be split later:建议用户确认后，在 aile-writing-plans 阶段处理
  8. If backfilling the archive system is recommended later: only write to analysis.md, prompting aile-writing-plans to convert it into an execution task
  9. (Optional) Generate the ADF content for the Jira Comment
  10. (Optional) Perform Jira write-back only when the user explicitly requests it and the tool explicitly supports ADF

Additional output format requirements

analysis.md must explicitly include:

## 子任务建议与决策

- 单据类型：缺失类 / 常规需求 / 待确认
- 是否建议创建子任务：否 / 是（需用户确认）
- 当前阶段是否允许创建：否
- 用户是否已明确授权：否 / 是
- 说明：...

## 档案系统回补建议

- 是否建议后续回补：是 / 否
- 建议回补文件：
  - `docs/specs/...`
  - `docs/modules/...`
- 回补原因：...
- 优先级：高 / 中 / 低
- 执行阶段：`aile-writing-plans` / `aile-executing-plans`
- 说明：本阶段只记录建议，不执行文档修改

If Jira write-back is needed, it must also be attached in analysis.md :

## Jira Comment ADF（待回填）

```json
{ ...ADF payload... }
```