technical-analysis-workflow
Use when you start an analiz task - explore every affected repository and resolve unknowns before writing the report
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- technical-analysis-workflow
- source
- obra/superpowers (MIT), adapted
- category
- architecture
- description
- Use when you start an analiz task - explore every affected repository and resolve unknowns before writing the report
03 SKILL.md 正文
Technical Analysis Workflow
Overview
Turn an analiz task into a fully-formed technical understanding through investigation, not guessing. The analysis report you write later — one HTML document whose sections are the spec and the plan (analiz-html-report) — is only as good as this grounding.
Hard gate: Do NOT write the report, or any implementation task, until you have explored the actual repository and resolved the ambiguities below. This applies to EVERY analiz task regardless of perceived simplicity — "simple" requests are where unexamined assumptions cause the most wasted developer work.
The Process
1. Clone and explore EVERY relevant repository first
- The analiz task's description lists the projects/repositories the PM believes are involved. Clone/pull ALL of them into your task workspace and review each — a cross-project feature is only understood when every affected repo is read.
- Project model first, before diving into code.
get_project_brief(repository_id)— stack, components, commands, conventions, reference docs.list_links(repository_id)— who calls what, including other repositories, so you can trace a contract to its consumers.list_component_checks— the commands the plan's verify steps will use, instead of inventing one.get_environment/list_runtime_errorswhen the request is about production behaviour. codebase_search,grep_code,expand_symbol_context,get_symbol_skeletonandread_fileonly cover the repository already in your workspace — they do not reach into a repository you have not cloned. Do not trust the PM's list as complete, and do not assume the tools will surface a repo you didn't open. To check for an affected repo the PM missed:list_repositoriesfor the remote/root of each candidate,run_terminalgit clone --depth 1 <remote_url or root_path> _analysis/<name>inside your workspace (an analiz run never publishes a branch, so this is safe), then pointgrep_code/read_fileatpath: "_analysis/<name>"and callget_project_brief/list_linkswith that repository's id. If you find an affected repo this way, include it in the analysis and note it in your review summary.- Explore before proposing anything: codebase_search for concepts, grep_code for exact symbols, get_repo_tree for structure, expand_symbol_context for focused reads.
- Read the repo's own rules:
CLAUDE.md,AGENTS.md,CONTRIBUTING.md,docs/adr/docs/decisions, lint configs. Their constraints go verbatim into the plan's Global Constraints block (implementation-plan-authoring). - Name the analog. State the closest existing feature (file:line) the new work follows. "No analog" must be said explicitly — it is a signal to take the heavier approach in step 4.
- Check third-party APIs against the locked version. Find the dependency's version in
go.mod/package.json/pubspec.lock, thenfetch_urlthe official docs for THAT version (orweb_searchto find them) before naming a function in the design. A call you did not see in the repo or in the docs for the locked version does not go in the plan. - Read existing docs and recent commits. Follow existing patterns — never invent a parallel convention.
- No commits. You are analysing, not implementing — never commit to any repo. Your entire output is the analysis report attached to the analiz task via add_task_document (
format: "html"), plus a summary add_task_comment. - Keep what you read. Note each file path and symbol as you read it — the report's
contextsection is a table of exactly these, and a path you did not see in this run has no place in it.
2. Understand the intent
- Restate the request in your own words: what outcome is wanted, for whom, and why. Write it in the report's
summaryas two lines — "Asked" (what the task literally says) separate from "Assumed" (what you inferred) — so a reviewer can tell your inference from the human's instruction. - Assess scope early: if the request describes multiple independent subsystems, decompose it into sub-analyses first — what are the independent pieces, how do they relate, in what order should they be built? Don't refine details of a project that needs splitting.
- Focus questions on: purpose, constraints, success criteria.
- Scale the analysis to the question, and when unsure, take the heavier path:
- Spike ("can we / is it possible…"):
summary,context, a findings-and-recommendation subsection,risks;planandsplitare omitted or say "none". - Bounded (a clear, contained change): all sections, kept short.
- Architectural (new integration, no analog, cross-repo, a schema or contract change): all sections, full depth, decision record (spec-authoring) and migration-and-contract-review where they apply.
- Spike ("can we / is it possible…"):
3. Identify WHAT and WHERE
- Name the units of work, their interfaces, and the exact files/areas each change touches.
- Design for isolation: each unit has one clear purpose, communicates through well-defined interfaces, and can be understood and tested independently. For each unit answer: what does it do, how is it used, what does it depend on?
- If you can't change a unit's internals without breaking its consumers, the boundary is wrong — fix the boundary in the design.
4. Propose approaches
- Propose 2–3 approaches with trade-offs; lead with your recommendation and the reasoning.
- YAGNI ruthlessly: strip anything the acceptance criteria don't require.
- Pick one approach and state every ambiguous point explicitly — a requirement readable two ways becomes a defect.
5. Resolve unknowns
- Resolve technical unknowns from the code, never by assuming.
- Only genuine PRODUCT decisions escalate — record them with
record_open_questions, never in the report's text and never withask_user(you have noask_usertool here). Default to non-blocking: a reasonable answer exists, so record it asrecommended_answerand keep going. Mark one blocking only when proceeding on any guess would waste the implementation (open-questions-protocol has the worked examples). Never block on a question the codebase can answer.
Output
This grounding feeds directly into the report: its context section (what exists, with real paths), then spec-authoring for the design section and implementation-plan-authoring for the plan section, all in the one document analiz-html-report describes. If you cannot yet name the files to touch and the interfaces between units, the analysis is not done.
Worked Example
Analiz: "Users can export a project's tasks to CSV." PM named the backend-api repo.
- Clone
backend-api.get_project_brief+list_linksfirst.codebase_search "task list endpoint"→ findTaskHandler+TaskRepository.ListByProjectalready exist → the export reuses them. - Cross-check:
list_repositoriesshows awebrepo (NOT named by the PM) linked tobackend-api.run_terminal git clone --depth 1 <web's root_path> _analysis/web, thengrep_code "api/v1/projects" path:"_analysis/web"→ the board page will need a download button. Addwebto the split. This is the PM-missed repo the cross-repo check surfaces —codebase_search/grep_codealone would not have found it, since they only cover the cloned, in-workspacebackend-api. - WHAT/WHERE: new
TaskExporterservice (backend) consumingListByProject; newGET /projects/:id/tasks/export; a web button calling it. - Approaches: (a) stream CSV from the handler, (b) build in a service and return bytes. Pick (b) — testable without HTTP. State it. Analog: the existing
/projects/:id/reportendpoint follows the same handler→service→repo shape (internal/adapter/http/report_handler.go:40) — bounded, not architectural. - Unknowns resolved from code (column order = the DTO fields). No stakeholder question needed.
Now the files and interfaces are named → analysis is done, the report can be written.
Red Flags
- "This is too simple to need analysis" — the design can be short, but it must exist.
- Proposing an approach before reading the relevant code.
- A spec section that says "TBD" or could be read two ways.
- Escalating a question you could answer with grep.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns