59 lines
11 KiB
Markdown
59 lines
11 KiB
Markdown
---
|
||
name: analyze
|
||
description: 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.
|