technical-analysis-workflow

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_errors when the request is about production behaviour.
• codebase_search, grep_code, expand_symbol_context, get_symbol_skeleton and read_file only 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_repositories for the remote/root of each candidate, run_terminal git 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 point grep_code/read_file at path: "_analysis/<name>" and call get_project_brief/list_links with 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, then fetch_url the official docs for THAT version (or web_search to 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 context section is a table of exactly these, and a path you did not see in this run has no place in it.