Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)
This commit is contained in:
octopus
@@ -0,0 +1,301 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user