sdlc/skills/analyze/SKILL.md

name, description

name

description

analyze

SDLC analysis stage. Gate on capability tags enforced in code by sdlc-gate (analyze requires reasoning-max), confirm the source branch, then pick a plan from PLAN_CONTENTS and question until consensus per references/consensus.md. Analyze its user stories against the current state (working directory plus REPO_{HASH} inventory for reuse), then run WBS with a standalone delivery/handover WP-01, CPM estimates and TDD todos. Write wiki page ANALYZE_{HASH} with real sample data, then close with tools/stage-report.sh - model tag verdict, worklog link, every wiki link written; logic only - never write code or modify files. Use after planning and before implementation; not for writing code (that is implement), and not before a plan exists in PLAN_CONTENTS.

analyze

Goal: create or extend the wiki analysis page ANALYZE_{HASH}. This skill is a logic-only stage: never output code, and never modify any file.

{HASH} = the shared wiki hash for {owner}/{repo} used to build the ANALYZE_{HASH} page name, computed by jsc-gitea/tools/hash-id (see jsc-gitea:wiki). All wiki reads and writes go through jsc-gitea:wiki.

Steps

1. Model gate and stage lock — run jsc-cli/tools/model-tags.sh sync, then jsc-hooks/hooks/sdlc-gate.sh lock analyze. This stage requires the reasoning-max capability tag. Rules: references/model-gate.md. Completion condition: the script exited 0, and you have reported the stage, the required tag, the model id, model source, and the verdict.

2. Confirm the source branch — the branch whose code counts as the current state:

   1. Run git fetch --prune origin first — without it, every origin/... reference is stale cache. Then report the working directory's current branch, the remote branches available (git branch -r; never git branch) and whether the working tree is clean.
   2. Ask per jsc-ask:ask rules which branch the analysis reads from; state the impact scope on every option (analysing the wrong branch produces work packages for code that does not exist).
   3. The current state is always the remote branch origin/{source-branch}, never the local one. The working directory's HEAD must point at the same commit as origin/{source-branch}; behind, ahead or diverged all mean you would be analysing code that is not what the remote holds. Report the gap (git rev-list --left-right --count origin/{source-branch}...HEAD) and stop — this stage never switches branches, never stashes, never pulls and never touches the working tree. Rules in references/branch.md.
   4. Record the confirmed branch and the head sha of origin/{source-branch} on the analysis page. Completion condition: the user has confirmed the branch explicitly; never infer it from the current checkout alone.

3. Read PLAN_CONTENTS via jsc-gitea:wiki for plans whose status is the literal 「未分析」 (name and HASH), and read ANALYZE_CONTENTS for existing analyses. Completion condition: you have listed every 未分析 plan with its name and HASH plus every existing analysis, or reported that a list is empty.

4. Let the user choose per jsc-ask:ask rules: extend an existing analysis or analyze a new plan. State the impact scope on every option. Completion condition: the user has picked one option explicitly, and you have named the target — the existing ANALYZE_{HASH} page, or the plan the new analysis covers.

5. Analyze the plan page's user stories one by one against the current state, questioning until consensus per references/consensus.md (the single authority for both planning and analysis): every answer produces the next question, and consensus needs both no output-changing unknown and the user's explicit confirmation. Never assume a missing detail, and never start the WBS while any item is still open. Current state means:

   1. Every file in the working directory, at the commit origin/{source-branch} points to (verified in step 2).
   2. Reuse an existing method or endpoint unless its logic cannot satisfy the requirement:
      • Check the REPO_{HASH} inventory page first. Re-inventory when the feature or endpoint is missing, or when the recorded commit sha differs from the current one.
      • Re-inventory MUST run as a sub agent: analyze the repository's features and endpoints, attach the current commit sha, write back to REPO_{HASH} with templates/repo-page.md, and update REPO_CONTENTS per templates/repo-contents.md.
      • For each reuse candidate, confirm the file path and method name first, then analyze whether its logic fits the requirement. Reject a candidate only for a stated reason, and record both the candidate and that reason in the analysis page's 複用決策 field.

   Completion condition: every user story has reached consensus under both conditions of references/consensus.md, and every reuse decision — reused, or rejected with its reason — is recorded in 複用決策.

6. Run a Work Breakdown Structure (WBS): split the user stories into work packages, number them sequentially (WP-01, WP-02, ...) and mark dependencies. Completion condition: every user story on the plan page maps to at least one numbered work package, and every dependency edge is recorded in the WBS table's 相依 column.

7. WP-01 is always the delivery/handover work package — see "Delivery package is WP-01" below. It stands alone, never merged into an implementation package, and every implementation package that consumes its spec depends on it. Completion condition: WP-01 is marked 交付 是 and holds only spec-shaped items, and every implementation package that consumes its spec names WP-01 in its 相依 column — or the no-handover case below is confirmed with the user and its reason is written on the page.

8. Estimate every work package's effort in hours and days with the Critical Path Method (CPM), and mark the critical path. Draw the critical path as a mermaid gantt chart per references/cpm-chart.md — its date/duration rules are mandatory, not a suggestion; skipping them is how the Invalid date rendering failure happens. Completion condition: every work package carries an hours figure and a days figure, the critical path plus its total days are written on the page, and the gantt chart follows references/cpm-chart.md exactly (integer-hour durations, after chaining, no dateFormat X).

9. 在 TDD 待辦前先產生 使用者故事驗收計畫，再把每個工作包拆進 測試計畫（TDD） 區塊，格式用 [ ]（未完成）與 [x]（完成）。每個使用者故事都要有驗收情境，並標明驗收方式是 真實資料 或 邏輯推論。簡單故事至少 1 個情境；中等故事至少 2 個情境，含 1 個主要流程與 1 個邊界或錯誤流程；複雜故事至少 3 個情境，含主要流程、邊界流程與失敗流程。每個情境都要寫出輸入、預期結果、資料來源與對應工作包。每個 TDD 待辦都是一個完整循環：一個接縫、一個先失敗的測試、一個最小實作、一次綠燈驗證，以及必要時的綠燈後重構。不要把紅燈測試、最小實作、綠燈驗證拆成不同待辦。接縫與反模式見 references/tdd.md。完成條件：每個使用者故事都在 ## 使用者故事驗收計畫 有情境；每個情境都有明確驗收方式與資料來源；情境數量符合複雜度；每個工作包都在 ## 測試計畫（TDD） 下有自己的小節；每個實作工作包至少有一個測試先行的 [ ] 待辦；每個待辦都寫出接縫、驗收情境、測試斷言行為、最小實作範圍與綠燈驗證方式。純交付工作包可以寫文件驗證或範例資料驗證待辦，但仍要寫出能證明規格可用的測試證據或審查證據。

10. Apply templates/analyze-page.md to create or update the analysis page and write it back via jsc-gitea:wiki. The page content is Traditional Chinese, exactly as the template dictates. Completion condition: the page is saved on the wiki and carries every section the template dictates, including the source branch, the head sha and the 未決項 section (「無」 when there is none).

11. If the analysis page is new: add it to ANALYZE_CONTENTS per templates/analyze-contents.md, and flip the plan's status in PLAN_CONTENTS to the literal 「已分析」. Completion condition: ANALYZE_CONTENTS shows the new row and PLAN_CONTENTS shows the literal 「已分析」, both saved on the wiki.

12. Stage report — the last thing this stage does, including every early stop (the model gate blocked, the working tree did not match origin/{source-branch}, no plan was selectable). Run tools/stage-report.sh analyze with one --page TYPE:{page} per wiki page this run wrote — ANALYZE_{HASH}, ANALYZE_CONTENTS, PLAN_CONTENTS, and REPO_{HASH} plus REPO_CONTENTS when a re-inventory happened — plus --worklog and --worklog-heading when a work log entry exists. No work log yet: write this stage's log content to a file and pass --pending-file {file} --log-hash {HASH} so it is held for the next jsc-log:worklog run. Rules and exit codes: references/stage-report.md. Exit 1 is a warning, never a block. Completion condition: the script's output is reported to the user verbatim, and every wiki page this run wrote appears in it.

Delivery package is WP-01

A work package is a delivery/handover package when someone else — another person, another CLI, another team — has to act on its output. Interfaces, schemas, spec documents, acceptance criteria and sample payloads are delivery output; endpoint bodies and UI wiring are not.

• WP-01 is the delivery/handover package, always first, always standalone. Pull every spec-shaped item out of the implementation packages and put it here. Never merge a spec into the package that implements it — merging removes the ability to hand the spec over early, which is the whole point.
• Implementation packages depend on WP-01 when they consume its spec, and they are the backup queue: still numbered, still estimated, still on the page, just ranked after it.
• Mark every work package as 交付 是 / 否 in the WBS table, and record WP-01's intended content type in the 交付型別 column when the user has already decided it (options in references/deliver-formats.md; the type is confirmed for real when implement starts that package).
• Dependencies still win among the rest: never place a package before one it depends on. Within the same dependency level, delivery-shaped packages come first.
• When nothing is genuinely deliverable (say, an internal refactor with no interface change), do not invent an empty WP-01: confirm with the user per jsc-ask:ask that this analysis has no handover output, then note the reason on the page and number the implementation packages from WP-01.

Sample data

Every sample value on the analysis page — request and response payloads, field values, config snippets, test fixtures — follows references/deliver-formats.md, which owns the source order, the labelling and the API-document layout. Record each value's origin in the WBS table's 資料來源 column. Completion condition: every sample value on the page carries a 資料來源 label of either 「真實：{source}」 or 「推論：無來源」, and no sample value contains personal data.

Hard limits

• Never output a code snippet (file paths and method names are allowed).
• Never modify any file in the working directory.
• Never switch, create or clean branches in this stage; ask the user to do it.