SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsaile-writing-plans

aile-writing-plans

Office & productivity

View repository

Updated 10-16 06:20

About this skill

Aile: Writing Plans (aile-writing-plans)

Source Original Skill

  • Source: Team-internal Phase 2 plan breakdown capability
  • Current positioning: Generate an executable plan based on requirements, documentation, and code context; if analysis.mdalready exists, prioritize inheriting and refining it

Overview

This is the team's own plan output skill, used to transform the input from Phase 1 (PM requirements + UI mockups) into the standardized output of Phase 2:

  • Main plan entry point:docs/plans/{Story-Key}/plan.md(if it already exists, use plan-{序号}.md）
  • Optional design files:docs/plans/{Story-Key}/design.pen
  • Priority context files:docs/plans/{Story-Key}/analysis.md

Assume the engineer has zero background on our codebase and questionable taste, then write a comprehensive implementation plan. Record everything they need to know: which files, code, and tests each task touches, the documentation they may need to check, and how to test it. Hand them the entire plan as small tasks.

Assume they are a skilled developer but know almost nothing about our toolset or problem domain.

Assume they do not understand good test design well.

Boundary constraints:

  • This skill is responsible for reading the Story description, existing documentation, and current code, and producing plan.md
  • If analysis.mdexists, it is the first-priority context; if it does not exist, the plan output must still be completed based on requirements and code
  • If analysis.md is confirmed to exist, this skill must transcribe the "archive system backfill suggestions" in it into executable plan tasks, so that the subsequent execution phase can actually perform the backfill
  • This skillis not responsible forcreating Jira Sub-tasks
  • This skilldoes not execute by default Jira write operations; if Jira changes are needed, they should be handled by a subsequent independent process

Workflow Overview

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

When to Use

Use in the following situations:

  • You already have the requirement description of the Jira Story
  • docs/plans/{Story-Key}/analysis.md already exists, or currently only the Story / code context is available
  • Need to produce an executable implementation plan with task granularity of 2-5 minutes
  • Need to convert requirement input or analysis results into an executable, verifiable, and handover-ready plan.md

Core Output Contract (Must Be Followed)

  1. The plan file must be located at:docs/plans/{Story-Key}/
    • The first plan file name is fixed as:plan.md
    • If plan.md already exists, the new plan must use:plan-{序号}.md(e.g., plan-1.md、plan-2.md）
    • 序号 increments from 1 starting at 1, always taking the next available number in the current directory
    • Overwriting existing plan files is prohibited (including plan.md and historical plan-{序号}.md）
  2. The file must contain:
    • Status management (overall progress, task status overview, execution records)
    • Requirement understanding, risks, and scope boundaries
    • UI / interaction constraints (if applicable)
    • Task breakdown (each task 2-5 minutes)
    • Test cases and acceptance criteria (testable, unambiguous)
    • AI execution guidelines (explicit execution order, constraints, manual Gate nodes)
    • Archive system backfill task (if analysis.md has suggested backfill)
  3. Each task must be described in TDD manner: RED → verify failure → GREEN → verify pass → REFACTOR → verify again
  4. State management must be traceable: each task must have 状态、负责人、开始时间、完成时间、阻塞原因, initial state uniformly 待开始
  5. Plan content must explicitly mark:
    • Original constraints in the Story description
    • analysis.md key conclusions (if present)
    • analysis.md archive system backfill suggestions (if present)
    • Implementation status derived from current code/tests/documentation
    • Key assumptions and items to be confirmed under missing context
    • Implementation decisions newly added during the planning phase
  6. Stopping plan generation is only allowed in the following scenarios:
    • There is a major conflict among the Story description, existing documentation, and current code status, and it cannot be reasonably determined which one should prevail
    • Story/requirement input is missing, and the goal of this change cannot be identified from the code and documentation either

Context degradation rules (must be followed)

  • Standard mode: exists analysis.md
    • Prioritize inheriting the requirement understanding, risks, acceptance criteria, and UI constraints therein
    • If it contains "archive system backfill suggestions", they must be transcribed into explicit tasks in the plan and must not remain at the suggestion level
    • Then use the Story, documentation, and code to verify the boundaries
  • Degraded mode: does not exist analysis.md
    • Plan generation must not stop
    • It must instead generate the plan based on the Story description, related documentation, current code, and test status
    • The plan must explicitly mark:当前计划未基于 analysis.md，属于降级生成
    • Must add:
      • Context source explanation
      • Key assumptions
      • Questions to be confirmed
      • Observations of current code status
  • Completion mode: analysis.md exists but the content is incomplete
    • Must not stop directly because a certain section is missing
    • The planning phase should fill in the minimum required information and mark the source in the plan:
      • From analysis.md
      • From Story
      • Derived from code
      • Filled in during the planning phase
  • Conflict mode: There is a major contradiction among different sources
    • Conflict points must be listed
    • User confirmation must be requested, or the basis for the judgment adopted in the plan must be clearly stated
    • Only when a low-risk judgment cannot be made is stopping allowed

Bite-sized task granularity

Each step is one action (2-5 minutes):

  • "Write a failing test" - step
  • "Run it to make sure it fails" - step
  • "Implement the minimum code to make the test pass" - step
  • "Run the tests and make sure they pass" - step
  • "Commit" - step

Context priority (must be followed)

  1. First priority: docs/plans/{Story-Key}/analysis.md(if present)
    • As the primary basis for task breakdown, risk boundaries, acceptance criteria, and testing approach
  2. Second priority: Jira Story description / AC / attachment links
    • Used to validate whether analysis.md deviates from the original requirements
    • When there is no analysis.md , it serves as the primary input for the plan
  3. Third priority: related specifications and module documentation
    • docs/specs/PRD.md
    • docs/specs/SAD.md
    • docs/modules/*.md
  4. Fourth priority: current state of code, tests, and configuration
    • Used to identify existing implementations, impact scope, reuse points, and validation entry points
  5. If the Story description conflicts with analysis.md :
    • Do not directly continue writing the plan
    • You must first mark the conflict points in the output
    • Prompt the user to first update analysis.md or confirm which version should prevail

Execution flow

At the beginning, state:"I am using the aile-writing-plans skill to generate the team plan."

Step 0: Read context

  • Read the Jira Story description, AC, and attachment links (if available)
  • Prioritize reading docs/plans/{Story-Key}/analysis.md(if it exists)
  • Read docs/README.md and related module documentation (if the impact scope involves docs/modules/*）
  • Read (if it exists)docs/specs/PRD.md、docs/specs/SAD.md
  • Read (if it exists) the plan artifacts prior to this Story (docs/plans/{Story-Key}/）
  • Read the current code, tests, and configuration to confirm affected modules, reuse points, and validation entry points

Step 0.1: Validate the analysis file

  • If docs/plans/{Story-Key}/analysis.md does not exist:
    • Do not stop
    • Explicitly output: the plan is currently being generated in "degraded mode"
    • You must instead rely on the Story, documentation, and current code state to complete the plan
  • If analysis.md exists but is missing sections:
    • Do not stop merely because sections are missing
    • You must list the missing items
    • During the planning phase, combine the Story, documentation, and code to fill in the minimum necessary information
  • If analysis.md does not exist and the Story information is weak:
    • You must first narrow the scope through code, tests, and module documentation
    • Add upfront in the plan tasks for "current state inventory / assumption confirmation / gap validation"
  • If the Story description clearly conflicts with analysis.md :
    • List the conflict points
    • Request user confirmation
    • Do not generate before confirmation plan.md
  • If even after combining code and documentation the minimum change goal cannot be determined:
    • Only then is stopping allowed
    • You must clearly explain what key information is missing

Step 1: Confirm Story-Key and scope boundaries

  • Clarify the Story-Key (for example ABC-123), as the directory name
  • Prioritize using analysis.md as the main basis to clarify "what to do / what not to do"; if it does not exist, summarize based on the Story + current code state
  • Use the Story description, documentation, and code to validate the boundaries and prevent omissions or deviations

Step 2: Task breakdown and sequencing

  • Task granularity: 2-5 minutes per task
  • Output: for each task, specify clear file paths, tests, validation commands, and expected output
  • Each task must be traceable to some source item:analysis.md, Story, documentation, or observations of the current code state
  • DRY: reuse existing patterns and do not add unnecessary abstractions
  • If missing analysis.md: Task 1 must prioritize "current state confirmation / test baseline / requirements boundary consolidation"
  • If analysis.md already contains "archive system backfill suggestions":
    • must be split into independent documentation tasks
    • each backfill task must specify the target file, backfill reason, trigger source, and acceptance method
    • these tasks enter the plan by default and must not be placed only in notes or the risk section

Step 3: Write to the plan file

First determine the "current plan file":

  • If docs/plans/{Story-Key}/plan.md does not exist: write to plan.md
  • If plan.md already exists: search in the order plan-1.md、plan-2.md… and write to the first nonexistent file
  • must not overwrite any existing plan file

Write the content to the "current plan file" and ensure it contains at least the following structure:

  • Document metadata (Story-Key, input source, generation date)

  • Context summary

    • Story description summary
    • analysis.md Key conclusion summary (if present)
    • Current code/test status summary

  • Task breakdown

  • Test and acceptance mapping

  • Execution order and manual Gate

  • Risks and items to be confirmed

  • Archive system backfill tasks (if analysis.md has recommended backfill)

  • If analysis.md does not exist or its content is incomplete: add a "Information to be completed during the planning phase" subsection and indicate the source for each item

  • If generated in degraded mode: add a "Degraded generation notes" subsection, stating that analysis.md was not read and the corresponding risks

  • Initialize the status management module:

    • Fill in the "overall progress"
    • Establish the "task status overview" (all tasks default to 待开始）
    • Establish the "execution record" and write the first record

Step 4: Commit Git changes (requires explicit user request)

  • Execute only when the user explicitly requests "commit code/commit changes" git commit
  • Commit only files related to the current Story (at least including the current plan file, and if necessary including design.pen）
  • Before committing, check the change scope to avoid mixing in unrelated files:
    • git status
    • git add docs/plans/{Story-Key}/
    • git status
  • Recommended commit message template:docs(plan): add {Story-Key} {plan-file}
    • plan-file Example:plan.md、plan-1.md
  • Example commit command:git commit -m "docs(plan): add {Story-Key} {plan-file}"

Step 5: Hand off to the execution phase

  • Recommended follow-up execution skills:aile-executing-plans or aile-subagent-dev