# Source Analysis & Review — Detailed Processes

> Extracted from `implement/SKILL.md` (Mode: port) Phase A1, A1.5, A1.7, A1.8.
> Read this file when executing the Source Analysis phases in standalone mode.

---

## Phase A1 — Understand Source

Read the source feature thoroughly — you must understand it well enough to
reimplement it from scratch in a different tech stack.

### Process

1. **Source code** — read every file in the source scope. Understand:
   - Public API (method signatures, request/response schemas).
   - Data model (entities, fields, relationships).
   - Business logic (validation, business rules, edge cases).
   - Error handling (exception types, error codes, error messages).
   - Configuration (environment variables, feature flags, constants).

2. **Source tests** — read all tests for the source feature. Tests are the
   authoritative specification of behavior. Pay attention to:
   - Happy path assertions.
   - Edge case and boundary condition tests.
   - Error path tests.
   - Mock/stub setup (external dependencies).

   After reading all source tests, run an automated extraction to seed the
   fidelity baseline:

   1. **For each test file**, extract every test case name (e.g. `describe`/`it`
      blocks, function names in test files).
   2. **Generate a raw FID list** — one `FID-*` entry per test case:
      | FID-* | Test Name | Source File:Line | Type |
      | ----- | --------- | ---------------- | ---- |
   3. **Do NOT skip** — every test case becomes a FID item. Missing FID items
      are the #1 cause of incomplete porting.
   4. **Save** the raw FID list to wiki page `port-{name}/source-analysis/fid-raw` (via `wiki 读写 API（见 TERMINOLOGY）`).

   In pipeline mode (Phase B1), this raw FID list feeds into `10-fidelity-baseline.md`.

3. **Source dependencies** — list every library, service, and infrastructure
   the source feature depends on:
   - Language runtime and version.
   - Framework (web framework, ORM, etc.).
   - Libraries (auth, logging, data parsing, etc.).
   - Infrastructure (database, cache, message queue, file storage).
   - External services (APIs, SaaS).

4. **Source Function Inventory** — produce a function-level catalog of every
   public API, private helper, and configuration constant in the source scope.
   This is the completeness audit trail — every unported function is visible.

### Output Templates

#### Source Analysis Document

```markdown
## Source Analysis: {source feature name}

### Public API

| Endpoint / Method | Input | Output | Error Cases |
| ----------------- | ----- | ------ | ----------- |
| ...               | ...   | ...    | ...         |

### Data Model

| Entity | Fields | Relations |
| ------ | ------ | --------- |
| ...    | ...    | ...       |

### Dependencies

| Dep    | Purpose   | Available in Target?     |
| ------ | --------- | ------------------------ |
| {name} | {purpose} | {yes / no / alternative} |
```

#### Source Function Inventory

```markdown
### Source Function Inventory

| Source File | Function / Symbol | Line | Type (public/private/config) | Ported? | Target Location |
| ----------- | ----------------- | ---- | ---------------------------- | ------- | --------------- |
| ...         | ...               | ...  | ...                          | ☐       |                 |
```

After Phase A5 (or at the end), require the Developer to backfill the "Ported?"
and "Target Location" columns. Add a note: "Any ☐ remaining in the 'Ported?'
column is a port gap."

---

## Phase A1.5 — Source Analysis Review (GATE)

Before proceeding to concept mapping, a reviewer (Explorer sub-agent) MUST
cross-check the source analysis deliverables against the original source files.
This is a lightweight but mandatory gate — source misunderstandings are the #1
root cause of incomplete porting.

### Review Process

1. **Spawn a reviewer** (Explorer sub-agent) with access to:
   - All source files in the original project (or their copies if offline).
   - All A1 deliverables: Source Analysis doc, Source Function Inventory,
     `fid-raw.md`.

2. **Reviewer checks (4 dimensions)**:
   - **SRC-CMP** (Completeness — **automated, not manual**): Does the Source
      Function Inventory list every public/private function, symbol, and config
      constant found in source files? This dimension MUST be verified by an
      automated symbol diff (see step 2.5), not by the reviewer reading source
      files one-by-one. Manual "looks complete" judgments are the dominant
      failure mode for port completeness — they are the reason functions get
      silently dropped. Any symbol present in source but absent from the
      inventory is a BLOCKER gap.
   - **SRC-API** (API Accuracy): Does the Public API table correctly capture
     every endpoint/method, its input/output schema, and all documented error
     cases? Compare against source route/method definitions and error handling
     code.
   - **SRC-TST** (Test Coverage): Does `fid-raw.md` contain one FID entry for
     every `describe`/`it`/`test` block in the source test files? Any test case
     without a FID is a gap. Does every FID reference the correct source
     file:line?
   - **SRC-DEP** (Dependency Accuracy): Are all libraries, infrastructure
     services, and external APIs the source depends on listed? Check source
     package manager files (`package.json`, `Cargo.toml`, `requirements.txt`,
     etc.) and imports.

2.5. **SRC-CMP automated symbol verification (mandatory)** — Enumerate every
   symbol the source actually exports, then diff against the Source Function
   Inventory. This converts "is the inventory complete?" from a subjective
   judgment into an objective set difference. **Do NOT skip even if codegraph
   is unavailable** — fall back to `grep`, never to a manual glance.

   ```bash
   # Preferred: codegraph symbol enumeration (one call per source file in scope)
   codegraph_node --symbolsOnly <source-file>

   # Fallback: grep for declarations in the source language
   grep -rEn '^\s*(export (async )?(function|const|class|interface|type|enum)|export \{|def |class |fn |public )' <source-dir>

   # Then diff the enumerated source-symbol set against the inventory's
   # "Function / Symbol" column. Every source-only symbol is a BLOCKER.
   ```

   Record the command used and the resulting symbol-set delta under dimension
   `SRC-CMP` in `source-analysis-review.md`. A review that omits this
   automated delta is itself a BLOCKER — the gate was bypassed, not passed.

3. **Output**: Reviewer writes findings to wiki page `port-{name}/source-analysis/review` (via `wiki 读写 API（见 TERMINOLOGY）`) with format:

   | Dimension | Finding | Severity (BLOCKER/MAJOR/MINOR) | Source Evidence |
   | --------- | ------- | ------------------------------ | --------------- |
   | SRC-CMP   | Missing function `validateSession` in `auth/middleware.js:45` | MAJOR | Source file line 45 |

4. **GATE**: All BLOCKER findings MUST be resolved (add missing items to
   inventory/fid list) before proceeding to Phase A2. MAJOR findings require
   documented justification if deferred.

5. **Pass condition**: Developer prints:
   `SOURCE ANALYSIS REVIEW COMPLETE — {N} BLOCKER items fixed, {M} MAJOR items documented`

---

## Phase A1.7 — Target Surface Analysis

> **Root cause addressed**: Ports fail when the target project's receiving
> surface is not analyzed. The Developer knows the source inside-out but has
> no systematic picture of what the target already has, what it lacks, and
> what structural changes are needed to receive the port. This phase closes
> that gap.

Analyze the **target project's current state** to establish the receiving
surface for the port. This is the mirror image of Phase A1 — instead of
understanding the source, you understand the target.

### Process

1. **Target directory tree** — map the target project's package structure,
   especially the packages that will receive ported code or that the source
   feature depends on. For monorepos, list every package and its role.

2. **Target existing capabilities** — identify what the target project
   already has that overlaps with or relates to the source feature:
   - Existing modules, components, services in the same domain.
   - Existing routes, providers, context hierarchy.
   - Existing schemas, migrations, config entries.
   - Existing CLI commands, flags.
   - Existing theme/style files.

3. **Automated structural diff** — run a source vs target comparison across
   multiple dimensions to surface gaps that manual reading misses:

   ```bash
   # Directory structure diff (source feature scope vs target equivalent)
   diff <(cd /source && find packages/app/src -name '*.tsx' | sort) \
        <(cd /target && find packages/app/src -name '*.tsx' | sort)

   # Dependency diff (package.json)
   diff <(jq '.dependencies | keys' /source/packages/app/package.json) \
        <(jq '.dependencies | keys' /target/packages/app/package.json)

   # Export symbol diff (if codegraph is available)
   diff <(codegraph exports @source-ai/app) \
        <(codegraph exports @target-ai/app)
   ```

   If `codegraph` is not available, use `grep` for exported symbols or
   `glob` for file presence. The goal is **systematic, not manual** —
   never rely on reading files one by one to discover what the target has.

4. **Integration point identification** — where in the target project will
   the ported code connect?
   - Route table changes (new routes, modified redirects).
   - Provider/context hierarchy changes (new providers, insertion points).
   - Schema/migration additions (new tables, new columns).
   - Config/settings additions (new config entries, new setting keys).
   - CLI command additions or flag additions.
   - Build config changes (vite/webpack/tsconfig).
   - Package.json dependency additions.

5. **Target readiness assessment** — does the target need structural
   refactoring before it can receive the port?
   - Does the target need a new package? (e.g. a new `packages/timeline/`)
   - Does the target need an interface extraction? (e.g. extract
     `ServerService` to an interface before porting a new implementation)
   - Does the target need a migration to add tables/columns?
   - Does the target need config schema changes?

### Output

Publish to wiki page `port-{name}/source-analysis/target-surface` (via `wiki 读写 API（见 TERMINOLOGY）`) using the format
in `reference/target-surface-template.md` (read it when executing this phase).

---

## Phase A1.8 — Capability Boundary Definition (GATE)

> **Root cause addressed**: Ports fail because the porting unit is "files"
> rather than "capabilities". A single capability (e.g. "draft/tab system")
> spans code files, type definitions, schemas, config, routes, providers,
> themes, and tests. When the Developer ports only the files they see and
> misses the implicit artifacts, the port is incomplete. This phase enforces
> a complete artifact inventory per capability before any implementation.

Define the **complete boundary** of the capability being ported. A capability
is not a file — it is the full set of artifacts required for the feature to
function in the target project.

### Artifact Dimensions

Every capability MUST be analyzed across ALL 13 dimensions listed in
`reference/capability-boundary-template.md` (read it when executing this
phase). The 13 dimensions are: source code files, type definitions/interfaces,
database schema/migrations, configuration entries, environment variables, CLI
flags/commands, theme/style files, route definitions, provider/context
hierarchy, build config changes, package.json dependencies, test files, and
shared package changes. A dimension with no artifacts is explicitly marked
"N/A — none required" (not silently skipped).

### Process

1. **For each dimension**, list every artifact:
   - **Source has**: what exists in the source project for this dimension.
   - **Target already has**: what the target project already has (from
     Phase A1.7 Target Surface Analysis).
   - **Needs creation / modification**: what must be created or changed in
     the target.
   - **Status**: ☐ not ported / ☑ ported / ⏭ N/A (none required)

2. **Cross-reference with Phase A1 Source Function Inventory** — every
   function/symbol in the inventory MUST appear in dimension 1 (source code
   files) or dimension 2 (type definitions). Any orphan is a gap.

3. **Cross-reference with Phase A1.7 Target Surface Analysis** — every
   "Gap" in the structural diff table MUST have a corresponding entry in
   the capability boundary. Any orphan is a gap.

4. **GATE**: All 13 dimensions MUST be filled in. A dimension with artifacts
   marked "☐ not ported" is acceptable ONLY if there is a documented deferral
   with a reactivation path (same rules as Phase A3 Gap Analysis). Dimensions
   that are "N/A — none required" must include a one-line justification.

### Output

Publish to wiki page `port-{name}/source-analysis/capability-boundary` (via `wiki 读写 API（见 TERMINOLOGY）`) using the format in
`reference/capability-boundary-template.md` (includes the full 13-dimension
table and output template).

### Pass condition

Developer prints:
`CAPABILITY BOUNDARY COMPLETE — {N}/{13} dimensions have artifacts, {M} dimensions N/A, {K} items deferred with reactivation path`

**Do NOT proceed to Phase A2 until this gate passes.** The capability boundary
is the single source of truth for "what must be ported" — every downstream
phase references it.