--- name: feature-analyzer description: "Use when analyzing feature branch changes across repos, planning implementation, or understanding backend→frontend contracts. Requires the source repository, target repository, and branch as confirmed input; the skill's PRE-STEP validates them before any analysis. NOT for: breaking an issue into implementable tasks (use issue-analyzer)." triggers: - "analyze feature" - "study module" - "investigate branch" - "Analyze branch" - "Analyze changes" - "Analyze commit" - "Study changes" - "Cross-repo analysis" - "Backend to frontend analysis" - "Feature analyzer" metadata: author: "MrCipherSmith" version: "2.4.0" category: "orchestration" compatible_harnesses: "cursor,codex,zed,opencode,claude" license: "MIT" --- If you were dispatched as a subagent to execute a specific task, skip this skill entirely. This skill is for orchestrators and interactive session-level routing only. Proceed directly with your assigned task. # Feature Analyzer --- ## Purpose Performs deep cross-repository analysis to understand business logic, architecture, API contracts, and implementation requirements. Generates structured documentation for both human developers and AI agents. Plan bridge: publish each `Step N` this run will take with `plan_set`, and update it with `plan_update` as it finishes — see the `session-plan-bridge` rule. **Two Analysis Modes:** **Mode A — Changes Analysis** (when base-branch provided): - Analyze what changed FROM base-branch TO current branch - Shows: additions, modifications, deletions - Use for: reviewing PRs, understanding feature implementation **Mode B — Current State Analysis** (when NO base-branch provided): - Analyze ENTIRE codebase as it exists NOW - Shows: existing functionality, architecture, patterns - Use for: understanding system, formalizing features, exploring codebase ## Input **Required context (ask before starting):** - Source repository path + GitHub repo + branch to analyze - Target repository path + current branch - Analysis mode (A: changes from base-branch, or B: current state) - Optional: GitHub Issue/PR URL, analysis focus keyword **Prepared input:** Use `.metaproject/skills/gdskills/orchestration/feature-analyzer/analysis-request.template.md` to prepare structured input. **Example:** See `.metaproject/skills/gdskills/orchestration/feature-analyzer/analysis-request.md` for a filled example. --- ## When to Use **Mode A — Changes Analysis:** - "Analyze feature branch changes from main" - "Review what changed in this PR" - "Compare feature-x with develop branch" **Mode B — Current State Analysis:** - "Analyze everything related to variables in pipelines" - "How does authentication work in this codebase?" - "Document the pipeline execution flow" - "Formalize the user management feature" --- ## User-Specified Analysis Focus When user specifies a focus area (e.g., "variables in pipelines"): **Priority Boost Rules:** - Files matching focus keywords → **Boost to P0** (even if normally P1/P2) - Files referencing focus entities → **+1 priority level** - Files in relevant directories → **+1 priority level** **Keyword extraction:** parse main concept ("variables") + context ("pipelines") from user request. > For detailed focus algorithm, bash search commands, and relationship mapping examples, see `SKILL.detail.md`. --- ## Workflow Copy this checklist and track progress based on your Analysis Mode: ### Mode A: Changes Analysis (with base-branch) ``` Analysis Progress - Mode A (Changes): 🚫 PRE-STEP: VALIDATE CONTEXT □ Source repository path: _____________ □ Target repository path: _____________ □ Branch to analyze: _____________ □ Base branch provided: _____________ (e.g., "main") □ Analysis Mode: A (Changes) □ User explicitly confirmed: _____________ □ Step 0.1: Check for existing analysis (cache lookup) □ Step 0: Gather context (source, target, branch, base-branch, focus) □ Step 1: GitHub MCP availability check □ Step 2: Analyze GitHub issue/PR (if provided) □ Step 3: Calculate BASE_SHA from merge-base (last branching point) □ Step 4: Collect git changes (git diff BASE_SHA..HEAD) □ Step 5: Categorize changed files: P0/P1/P2; apply focus boost □ Step 6: Select 3-7 key files; Deep Dive — read selected files □ Step 7: Analyze related tests □ Step 8: Cross-repo dependency analysis □ Step 9: Intermediate review (show user, wait for confirmation) □ Step 10: Generate documentation □ Step 11: Final validation and delivery □ Step 12: Post-analysis (update doc registry) ``` ### Mode B: Current State Analysis (without base-branch) ``` Analysis Progress - Mode B (Current State): 🚫 PRE-STEP: VALIDATE CONTEXT □ Source repository path: _____________ □ Target repository path: _____________ □ Branch to analyze: _____________ □ Base branch: NOT PROVIDED (Mode B) □ Analysis Mode: B (Current State) □ User explicitly confirmed: _____________ □ Step 0.1: Check for existing analysis (cache lookup) □ Step 0: Gather context (source, target, branch, focus) □ Step 1: GitHub MCP availability check □ Step 2: Analyze GitHub issue/PR (if provided) □ Step 3: SKIP (no base-branch comparison) □ Step 4: Search ENTIRE codebase for focus-related files □ Step 5: Discover and categorize ALL relevant files: P0/P1/P2; apply focus boost □ Step 6: Select 3-10 key files; Deep Dive — read to understand functionality □ Step 6.5: FORMALIZE functionality (business logic, API contracts, state, data flow) □ Step 7: Analyze tests (understand coverage) □ Step 8: Cross-repo dependency analysis (find usages) □ Step 9: Intermediate review with formalization □ Step 10: Generate documentation (Feature Specification) □ Step 11: Final validation and delivery □ Step 12: Post-analysis ``` --- ## Step 0: Context Gathering (MANDATORY) **CRITICAL**: User MUST specify both Source and Target repositories. **Ask all questions in one message:** ``` For cross-repository analysis, I need: 1. **SOURCE Repository** (where to analyze): - Local path: ? - GitHub repo (owner/repo): ? - Branch to analyze: ? 2. **TARGET Repository** (where implementation will happen, if applicable): - Local path: ? - GitHub repo (owner/repo): ? - Current branch: ? - (Can be same as source for single-repo analysis) 3. **Analysis Mode**: A. Changes Analysis — compare against base-branch (what changed) - Base branch: ? (e.g., "main", "develop") B. Current State Analysis — analyze codebase as-is (no base branch needed) 4. **Ticket/Reference** (GitHub Issue/PR URL, optional): ? 5. **Analysis Focus** (optional): specific area, e.g., "variables in pipelines", "auth changes" ``` **No default paths** — user must provide all locations explicitly. **Before Step 1, verify context is complete:** ``` CONTEXT VALIDATION: IF Source, Target, or Branch is missing → STOP, ask for missing info IF Analysis mode not specified → ASK: Mode A (changes from base) or Mode B (current state)? IF Mode A and no base branch → ASK: "What is the base branch?" IF user says "just use current directory" → EXPLICITLY CONFIRM the path before proceeding ``` > For detailed decision tree and conversation example, see `SKILL.detail.md`. --- ## Step 1: GitHub MCP Availability Check Before starting analysis: - Try to fetch simple repo info via GitHub MCP - If unavailable: notify user, offer Option A (restart MCP) or Option B (git-only, limited context) --- ## Step 2: GitHub Issue/PR Analysis (if provided) - Fetch Issue/PR and all comments via GitHub MCP - Understand business goal — what problem does the feature solve? - Extract acceptance criteria and requirements --- ## Step 3: Git Changes Collection **CRITICAL**: Find the last branching point (merge-base), NOT the current HEAD of the parent branch. This ensures you analyze only feature branch changes, not unrelated changes from other merged PRs. ```bash # Find branching point BASE_SHA="$(git merge-base HEAD )" # Collect changes git log --oneline "${BASE_SHA}..HEAD" git diff --stat "${BASE_SHA}..HEAD" git diff --name-status "${BASE_SHA}..HEAD" git diff "${BASE_SHA}..HEAD" ``` > For the full BASE_SHA detection algorithm (with fallback logic for main/master/upstream), see `SKILL.detail.md`. --- ## Step 4: File Categorization and Prioritization ### Priority Levels **P0 — must analyze**: - API contracts: DTOs, interfaces, type definitions - Public API endpoints (controllers, routes) - Database schema changes, auth changes, config changes **P1 — SHOULD ANALYZE (Important)**: - Business logic (services, use cases) - State management (stores, contexts) - Error handling, validation logic **P2 — NICE TO HAVE (Optional)**: - Pure UI components, refactoring, tests, docs, package updates ### Standard File Selection From P0: select up to 5 most important (sort by API contracts → business logic → infrastructure). From P1: select up to 3 if P0 < 3. Skip P2 unless P0+P1 < 3. When focus specified: boost files matching focus keywords to P0; select ALL focus-matching P0 files. > For the full focus-based selection algorithm with examples, see `SKILL.detail.md`. --- ## Step 5: Deep Dive Protocol **A git diff alone does not support a conclusion. Also do this:** 1. **Read selected files**: - Small/medium files: read completely - Large files (> 500 lines): use outline/grep to locate relevant sections, then read only those ranges 2. **Understand context**: architecture role, dependencies, what depends on it 3. **Find and analyze tests**: look for matching test files, understand coverage 4. **Check rules compliance**: verify against `code-style-patterns.mdc` --- ## Step 6: Cross-Repository Analysis (Source → Target) 1. **Dependency search**: find all target files importing changed DTOs/APIs from source 2. **Contract divergence**: compare new source contracts with current target implementation 3. **Target deep dive**: read 2-3 key components that will need changes 4. **Target rules compliance**: check `.metaproject/rules/core/*.mdc` in target repo --- ## Step 7: UI Analysis (if applicable) Check `AGENTS.md` for available tools (`playwright-testing.mdc`, `storybook-guidelines.mdc`). Analyze visual regression requirements, component behavior changes, accessibility impact. --- ## Step 8: Integration with Other Skills Before finalizing, consider running: - `skills/review/code-style-review` — if architecture changes detected - `skills/review/code-ai-review` — for self-validation of findings - `skills/review/code-mobx-store-review` — if store changes found --- ## Step 9: Intermediate Review After completing analysis, **show user** before generating full report: ``` ═══════════════════════════════════════════════ INTERMEDIATE ANALYSIS SUMMARY ═══════════════════════════════════════════════ Scope: - Source: [repo] @ [branch] - Target: [repo] @ [branch] - Files analyzed: [N] (P0: [N], P1: [N]) - BASE_SHA: [sha] Key Findings: 1. [Brief finding 1] 2. [Brief finding 2] Cross-Repo Impact: - [ ] Breaking API changes detected - [ ] New endpoints to implement - [ ] DTO changes affecting frontend Estimated Complexity: [Low/Medium/High] Continue to full documentation? [Y/n] ═══════════════════════════════════════════════ ``` Wait for user confirmation before generating full report. --- ## Step 10: Documentation Generation ### Output Structure ``` /analysis// ├── report.md # Findings, API contract diff, DTO comparison, cross-repo impact, analysis metrics └── implementation-plan.md # Actionable implementation plan derived from the analysis ``` No date-stamped folder: update `report.md`/`implementation-plan.md` in place for a rerun on the same feature rather than creating a parallel copy. Default output is a single English (`en`) pair. Add other language variants only if the user explicitly asks for them, and keep any variants you create synchronized. `report.md` should use Gherkin-style scenarios where they make findings easier for other AI agents to parse. > For full Gherkin output format and syntax rules, see `SKILL.detail.md`. --- ## Step 11: Content Requirements - Every claim MUST reference specific code: `[filename.ts:L123](file:///absolute/path#L123)` - Minimum 3 code examples per report - Mermaid diagrams for architecture, tables for DTO changes, flowcharts for data flow - Default to a single `en` document; add `ru`/`ai` (or other) variants only when the user explicitly asks, keeping them synchronized --- ## Step 12: Error Handling | Situation | Fallback | |-----------|----------| | GitHub MCP unavailable | Use git history only; notify user | | No tests found | Note risk, recommend coverage | | Cannot determine BASE_SHA | Ask user for parent branch, or use `--first-parent` estimate | | Empty diff | Check staged (`--cached`), untracked (`git status`), wrong branch | | Cross-repo access denied | Ask for manual path, or do source-only analysis | --- ## Step 13: Analysis Metrics Track and include in the `## Analysis Metrics` section of `report.md`: - Duration, files analyzed (P0/P1/P2), lines changed - Cross-repo dependencies, API endpoints changed, DTOs modified - Breaking changes count, test coverage %, risk level - Complexity score: `(P0×3) + (P1×2) + (P2×1) + (breaking_changes×5)` — 0-10 low, 11-25 medium, 26+ high --- ## Step 14: Validation Checklist Before finalizing: - [ ] All P0 files analyzed completely - [ ] Target repository analyzed (if cross-repo) - [ ] Minimum 3 code examples included - [ ] All file references include line numbers - [ ] API contracts documented - [ ] Breaking changes clearly identified - [ ] Implementation plan provided - [ ] Metrics calculated - [ ] User approved intermediate review --- ## Step 15: Post-Analysis Follow `documentation-management.mdc`: update `/readme.md`, add entry to analysis index, tag with keywords. --- ## Rules and Guidelines 1. **Always follow** `documentation-management.mdc` for doc structure 2. **Always check** `code-style-patterns.mdc` for compliance 3. **Always use** AGENTS.md to discover available skills and tools 4. **Never assume** — ask user when unclear 5. **Never skip** intermediate review for complex analyses (P0 files > 3) 6. **Always provide** concrete, actionable recommendations 7. **Always default** to a single-language document (`en`); add other language variants only when the user explicitly asks --- ## Red Flags Stop and re-read this skill if you are thinking: | Rationalization | Rebuttal | |---|---| | "The user named a branch, so I have enough to start." | The PRE-STEP needs source repo, target repo and branch, each confirmed. A branch without its repo pair is how a cross-repo analysis quietly becomes source-only and reports no frontend impact because it never looked at the frontend. | | "`git diff` came back empty, so the branch changed nothing." | Step 12 names the three usual causes: the wrong BASE_SHA, changes that are staged or untracked, and the wrong branch checked out. Report "no changes" only after `--cached`, `git status` and the branching point all agree. | | "I read the diff hunks, so I understand the change." | A hunk shows the lines that moved, not the contract they belong to. The Deep Dive Protocol reads P0 files whole because the breaking part of a change is usually the caller the diff never touched. | | "The finding is clear from the code I just read — the line reference can wait." | Step 11 makes a `file:L123` citation mandatory for every claim. An uncited claim cannot be checked by the developer acting on it, and a report of uncited claims is indistinguishable from a plausible guess. | | "There are 6 P0 files but the picture is obvious, so I'll skip the intermediate review." | Rule 5 forbids skipping it above 3 P0 files. The intermediate review is the only point where the user can correct the scope before a full report is written against the wrong one. | | "An analysis for this feature already exists, so I'll write mine into a new folder." | Step 10 requires updating `report.md` and `implementation-plan.md` in place. Parallel copies mean the next reader picks one, and nothing marks which is current. | | "GitHub MCP is unavailable, so issue and PR context is out of reach." | Step 12's fallback is git history plus a notice to the user — not silence. An analysis that drops the issue context without saying so reads as if the issue held nothing relevant. | --- ## Exit Criteria Do not report the analysis as complete until all of these hold: - The PRE-STEP inputs (source repo + branch, target repo + branch, mode) were confirmed by the user, not inferred — and the report states them. - Mode A: `BASE_SHA` is recorded in the report. Mode B: the report says explicitly that it describes current state, not a diff. - Every P0 file was read in full and appears in the analysed-files list; the P0/P1/P2 counts in `## Analysis Metrics` match that list. - `report.md` contains at least 3 code examples, and every claim carries a `file:line` reference. - API contracts and breaking changes each have a section — a "none found" is written out with what was checked to reach it. - `implementation-plan.md` exists and every step names a file or module to touch; no step reads "investigate". - `## Analysis Metrics` includes the computed complexity score and its inputs. - The user answered the intermediate review prompt (mandatory whenever P0 files > 3), and any correction they made is reflected in the final report. - Step 15 post-analysis is done: `/readme.md` and the analysis index name this analysis. --- > **Extended documentation**: detailed analysis mode descriptions, file selection algorithms, Gherkin output format, cache/existing-report handling, and full examples are in `SKILL.detail.md`.