Octopus/octopus-workflow
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial publish v0.1.0: standalone workflow core (corpus + examples + guards)

Browse Source
This commit is contained in:
octopus
2026-09-15 08:41:51 +08:00
commit bb35e661b2
114 changed files with 20240 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/skills/implement/SKILL.md
+350
View File
@@ -0,0 +1,350 @@
---
name: implement
description: >
Use ONLY when implementing a work item from an approved iteration plan,
OR fixing a bug (bugfix mode), OR refactoring code (refactor mode),
OR porting a feature (port mode). The Developer (Worker) reads the work
item, design sections, and acceptance criteria, writes code, and
self-checks against the relevant checklist before handing off to code
review.
# `stage` is intentionally omitted: `implement` is a production-phase name the
# stage registry rules invalid post-[org-internal #3072] phase 3 (see
# core/schemas/workflow-routing.schema.json stage enum — production-phase
# names are "no longer valid anywhere"). The implement skill has no registry
# gate id; the gates it feeds into are `review-code` and `verify`.
triggers:
- implement
- implement work item
- implement WI-
- work item
- 实现工作项
- 开始写代码
- implement the iteration
- bugfix
- fix a bug
- fix bug
- fix this bug
- 修复
- 修复bug
- help me fix
- doesn't work
- does not work
- not working
- is broken
- stack trace
- throws an error
- crashes
- refactor
- 重构
- restructure
- 删除死代码
- dead code
- improve code structure
- 重新组织代码
- graduate experimental
- remove experimental guard
- 移除实验性
- port
- porting
- port feature
- port this feature
- migrate feature
- 移植
- 迁移功能
- code change
- write code
role: Producer
---
> Core 中立版（Increment 6a 改写，原 deferHard verbatimDir）。机制、结构与 frontmatter 保持；实例术语（工具名、路径、工单号）按 `core/adapters/TERMINOLOGY.md` 绑定到具体实例。
# Skill: implement
## Mode Selection
This skill handles four work modes. The main session identifies the mode from the work item's `type` field or the user's request:
| Mode | When to use | Key difference |
|---|---|---|
| **implement** (default) | Work item from an approved iteration plan | Standard implementation per acceptance criteria |
| **bugfix** | User reports a bug / fix request | Reproduce → root cause → regression test (must FAIL first) → minimal fix |
| **refactor** | User asks to restructure code (no behavior change) | Establish baseline → transform in ≤10 steps → verify zero regression |
| **port** | User asks to port a feature from another project | Read source → map concepts → implement in target conventions → verify fidelity |
In **standalone mode** (user-initiated, no iteration plan), skip preconditions about plan/approval and go directly to the mode-specific workflow.
In **pipeline mode** (work item from iteration plan), follow the standard preconditions then the mode-specific phases.
**On-demand references**: each mode's phase-by-phase detail (templates, prompts, orchestration flows, historical notes) lives in `reference/{mode}-mode.md`, NOT injected — read it at mode entry. Full read-timing table: References section.
> **Progressive disclosure ([org-internal #3734])**: when dispatching a Developer scoped to
> one mode, pass `skills: ["implement:mode-bugfix"]` (preamble + that
> mode's workflow only) instead of the full body; pipeline-mode dispatches
> should also carry `pipeline-detection`
> (`"implement:mode-implement,pipeline-detection"`). Mode Selection, Agent
> Role, Greenfield vs. Brownfield, … are unmarked preamble and always
> inject. Full-body remains the default when no selector is passed.
## Agent Role
The implementation is owned and produced by the **Developer** (Worker). The Builder delegates each work item to a dedicated Developer sub-agent with the full design and plan context.
> **Role naming**: throughout this skill, "Builder", "Orchestrator", and "main session" name the same coordinating role (the main session that dispatches Developer sub-agents and validates output) — not a distinct role from the "Orchestrator" used by `review-code` and the shared review pipeline.
The Developer is responsible for:
- Reading the assigned work item, design sections, and acceptance criteria.
- Writing code that faithfully implements the design.
- Running typecheck, lint, and tests to self-verify.
- Self-checking against the relevant checklist before handoff.
- Persisting the final report to disk before returning — worker-report persistence ([org-internal #2847], see `../_shared/worker-report-persistence.md`).
- Writing no more and no less than the work item scope — no opportunistic refactoring of unrelated code.
The Builder's role is to validate the implementation output and pass it to code review. The Builder MUST NOT write or revise implementation code.
### Pre-flight checklist injection ([org-internal #2599])
Before dispatching ANY Developer (or Tester) sub-agent — in every mode (implement / bugfix / refactor / port; pipeline or standalone) — the orchestrator resolves the ticket's route (the Process Assessment Gate Step 0 already resolves the Kind/* route) and reads `<instance-root>/workflow-routing.yaml` `routes.{Kind}.preflight`. When the list is non-empty, prepend it to the sub-agent's task prompt as:
```
Pre-flight self-check (evidence-based, from retrospective — verify each
BEFORE writing code; if one is already satisfied, note why in impl-notes):
1. {item} (evidence: {evidence})
2. ...
```
Rules:
- The list is a human-landed checklist (retro proposes, a human lands it) — NEVER synthesize or extend items at dispatch time.
- Cap at `preflight.max_items` entries; beyond it, drop oldest by `added_cycle`.
- Items are self-checks, not gates: an unsatisfied item means the Developer addresses it in the implementation (and says how), not that dispatch aborts.
<!-- inject: ../_shared/large-prompts.md -->
> **Context compaction**: this skill is a pipeline stage boundary. The main session (orchestrator) compacts at this clean boundary ONLY when a capacity/projection trigger holds, per the L1 rule `core/rules/compact.md` §"Stage-boundary compaction" (long multi-stage runs — DAG Epic orchestration — keep the legacy every-boundary compaction; short runs — bugfix / DAG task — and standalone runs default to NOT compacting). The sub-agent this skill dispatches persists its artifacts to the Gitea wiki under `{slug}/` as it goes, so a mid-run compaction loses nothing — re-read the stage's wiki index to resume.
## Role Split: Developer vs Tester
Each execution mode below defines its own Tester focus and any mode-specific orchestration overrides.
## Greenfield vs. Brownfield
**Greenfield** (new project): Create new files following the design. Project conventions are defined by the design document.
**Brownfield** (existing project + new feature):
- **Read neighbors first.** Before writing code, read at least 3 existing files in the same module to absorb the project's code patterns. (Shared brownfield rule — canonical statement: `core/skills/review-code/SKILL.md` §"Greenfield vs. Brownfield"; the threshold and same-module scope are defined there.)
- Match existing conventions exactly: error handling style, logging format, naming, file structure, import ordering, type declaration placement.
- New code MUST follow existing conventions consistently — no style drift.
- No opportunistic refactoring of unrelated existing code. If you see a bug or improvement opportunity in unmodified files, log it in the implementation report as a separate observation — do not fix it in this work item.
- Phase 1 (Parse Context) includes reading neighboring code files to establish the project's conventions. Phase 4 (Self-Check) compares new code against these conventions.
---
## Execution Modes
<!-- section:mode-implement -->
### Mode: implement (default)
Standard workflow for work items from an approved iteration plan. Full phase detail, templates, prompts: `reference/implement-mode.md` (read at mode entry).
#### Preconditions
> **DAG-mode input path** (DAG ticket pipeline — `Kind/Epic` / `Kind/Feature` DAG parent, routes-table direct): DAG-routed tickets **ignore `Size/*`** — the tiered Preconditions below are replaced by the node spec: work item + acceptance criteria resolve from the **frozen DAG copy** wiki page `{epic-slug}/dag` (+ `{epic-slug}/dag-nodes/{node-id}` subpages when AC detail is sunk) and the node ticket's issue body — no legacy `{slug}/04-plan-*` page, no `Size/*`-tiered req/design page. The design-space + iteration-plan convergence preconditions are replaced by the **review-dag single-gate convergence**: `octopus review status --stage review-dag` must show `success` before the node is implemented.
> **DAG-route read map** (every legacy `{slug}/04-plan-*` / `{slug}/03-design-*` reference below resolves from the frozen DAG copy instead — mirror of `verify/SKILL.md`'s DAG branch; full map: `reference/implement-mode.md` § Preconditions):
>
> - Work item (`04-plan-04-iteration-assignment` / issue body) → node spec in `{epic-slug}/dag` + node ticket body.
> - Acceptance criteria (`04-plan-05-acceptance-criteria` / issue body) → node `acceptance_criteria` (+ sunk subpages) + node ticket body.
> - `test_id` (測試用例 ID) → the `test_id` declared on the node AC in `{epic-slug}/dag`.
> - Design sections / interface design (`03-design-**`) → node spec + cross-session edge contracts (no design page).
> - Component mapping (`03-design-08-traceability`) → node `req_refs` + component field.
>
> At Phase 6 handoff, pass `mode: "dag-task"` to review-code (its DAG Task Mode keys off the same frozen-DAG-copy detection).
> **Legacy pipeline preconditions retired ([org-internal #3072] phase 3, 2026-08-21)**: tiered artifact-existence and review-convergence checks belonged to the archived legacy pipeline. Live input modes: DAG task mode (above) and standalone modes (the request itself is the spec). Historical tiered publish targets: `reference/implement-mode.md` § Legacy notes.
Before starting implementation, confirm:
- [ ] Work item is specified (DAG node ticket `{node-id}`, or a clear task description in standalone modes).
- [ ] `core/checklists/implementation.md` is accessible.
- [ ] `slug` matches the run's slug (DAG: `{epic-slug}`).
- [ ] 跨阶段门控清单: `core/checklists/pipeline-gate.md` accessible and its DAG 路由变体 section confirmed — frozen DAG copy exists, single gate converged, upstream dependencies at terminal state (`ready`); else abort, listing the blocked nodes.
**If any precondition is unmet, abort and inform the user** — list every missing artifact, un-converged review, and blocked dependency (complete gate checklist + Recovery Protocol: `core/checklists/pipeline-gate.md`). When no work item is specified, resolve the ready/pending task nodes from `{epic-slug}/dag` and present them for selection (prompt: `reference/implement-mode.md` § Preconditions — work-item selection).
#### Phases skeleton
Every gate below is hard — agents rationalize skipping exactly these. Full detail: `reference/implement-mode.md`.
1. **Phase 1 — Parse Context**: read the work item (node spec + node ticket), acceptance criteria (every falsifiable `AC-{n}` / `NFR:` entry and its declared `test_id`), design context (cross-session edge contracts), and the existing codebase; resolve inputs per the DAG-route read map (standalone: the request). Read every referenced design file before writing code.
2. **Phase 2 — Plan Implementation**: brief plan (template: `reference/implement-mode.md` § Phase 2). GATES: **≤ 3 files per work item** (more → the Builder/user MUST split it); every file must map to a design component (else flag the design gap and abort); do NOT invent design decisions. Present the plan and ask: proceed? (yes / no / revise).
3. **Phase 3 — Implement**: design-exact code; tests cover every AC.
- **Design discipline**: component interfaces, method signatures, return types, data model fields, API endpoints/schemas/status codes MUST match the design exactly; an impossible design decision → stop and report the gap, never silently deviate.
- **Test discipline (Red → Green, declared test_ids)**: write each declared test FIRST and confirm it fails for the intended reason (Red) before writing the implementation (Green); the test's `file-path :: test-name` MUST match the declared `test_id` exactly — the implement-side handshake with `verify` (DOD-1.6). `MANUAL` / `BENCH:<script>` test_ids are exempt from the Red step; an already-passing test is noted in the Phase 5 report, not forced to fail.
- Code quality + incremental commitments (conventions, no unjustified dependencies, public-API docs; shared types → data access → logic → handlers, typecheck per unit): `reference/implement-mode.md` § Code Quality.
4. **Phase 4 — Self-Check** (all mandatory):
1. `bun typecheck` (or project-equivalent) — zero errors.
2. `bun oxlint --deny-warnings` (repo root — the review-code mechanical gate's canonical lint invocation; `bun lint` is the package-script alias) — zero errors.
3. `bun run test:changed` (or project-equivalent; full suite `bun run test:parallel` is verify's job, not a per-revision gate, [org-internal #2598]) — all tests pass.
4. Post-deletion cleanup (when any code was removed): re-run lint + typecheck to catch orphaned imports/variables/type references.
Then self-check `core/checklists/implementation.md`; every new function/method/exported API has ≥ 1 test; interface promises cross-checked against the node's edge contracts. **Review-readiness GATE**: self-attest `core/checklists/code-review.md` (COR, DGN, SEC, PERF, TST, STY, DBT, A11Y, DOC, TRC), record pass/fail per dimension in the Phase 5 report; handoff requires **0 BLOCKERs and 0 MAJORs** — if you can find a MAJOR, the formal review will too; fix it now.
5. **Phase 4.5 — Iteration Completion Commit**: after ALL work items in the iteration pass Phase 4, commit with format `[{chunk-id}][{iteration}] {summary}`; commit body REQUIRED for non-trivial commits (> 1 file or > 20 LOC): What (files + purpose + the `WI-{NNN}` ID — code-review TRC 10.1), Why (design/REQ motivation), Evidence (test names / verification commands). Full rules: `reference/implement-mode.md` § Phase 4.5.
6. **Phase 4.6 — Issue Checklist Sync (progressive)**: after committing, mark items this iteration delivered `- [x]` + `_(commit {sha}: file/component)_` per the `issue-checklist-sync` L1 rule; do NOT touch items outside this iteration's scope.
7. **Phase 4.7 — PR-Creation Sync**: the session pushes its branch and reports `status=done branch=<ref> verify=… risk=…` — the orchestrator opens the PR (serially per TD-678/[org-internal #4425]) and applies the `Risk/*` label from the report's `risk=` hint, computed per the risk-classifier frozen table (`HIGH_RISK_GLOBS` in `.gitea/scripts/risk-classifier.ts`: core/migrations/deploy/`core/rules/**`/`.gitea/workflows/**` → `Risk/High`, else `Risk/Low`); `Risk/High` PRs merge manually by design. Once the PR exists, ensure `## 当前状态` exists (PR / 代码评审 / CI rows are written by the `status-sync` poller, NOT by hand); append the PR reference to the matching Epic task-list row. **Never hand-sync main into the PR branch** — that is the keep-mergeable workflow's job. Detail: `reference/implement-mode.md` § Phase 4.6 / § Phase 4.7.
8. **Phase 5 — Report**: implementation report with AC → test traceability (template: `reference/implement-mode.md` § Phase 5). **Persist before returning ([org-internal #2847])** — the Developer's LAST action before returning the report: write it to `<runs-root>/{slug}/workers/{chunk-id}-worker-{seq}.md` (Tier 1 run workspace) else `/tmp/octopus/{chunk-id}-worker-{seq}.md` (`../_shared/worker-report-persistence.md`). The persisted copy is the report of record — applies to EVERY mode's report phase.
9. **Phase 6 — Handoff to Code Review**: present the report; signal readiness via `signal_stage_done`. Do NOT mark the work item complete until code review passes.
#### Tester focus & Common Rationalizations
Boundary + contract tests — the cases the Developer is structurally biased to miss; every acceptance criterion MUST map to ≥ 1 test. Implementation fails far more from **pressure** than from ignorance — full detail (11-row Excuse → Reality table): `reference/implement-mode.md` § Tester focus for implement / § Common Rationalizations.
---
<!-- section:mode-bugfix -->
### Mode: bugfix
Reproduce, isolate, and fix a bug with a regression test that MUST fail before the fix. Small localized bugs → standalone (existing system behavior is the specification; review gate optional — only when > 20 lines or ≥ 3 files); large/complex bugs → pipeline (review + verify mandatory). Phase detail, templates, prompts: `reference/bugfix-mode.md` (read at mode entry).
> **Routing override (ticket-seeded)**: the Optional/None gate above applies to *user-initiated* standalone mode. A `Kind/*` route whose `keep_gates` includes `review-code` / `verify` (e.g. `Kind/Bug`, `Kind/Testing`) makes those gates MANDATORY regardless of size (a gate is mandatory if EITHER the route OR the skill requires it; skipping is valid only when BOTH agree).
#### Phases skeleton
The regression test MUST fail before the fix — the Tester dispatches between Phase 2 and Phase 4, not after the fix (dispatch flow: `reference/bugfix-mode.md` § Role & Responsibilities; single-Developer invocation only for trivial single-file fixes — force the split when the fix touches ≥ 2 files or the root cause spans ≥ 2 levels of indirection).
1. **Phase 1 — Understand & Reproduce**: read relevant code; check existing tests (a passing test on this path → the bug is in the test or an uncovered branch); reproduce and document (template: `reference/bugfix-mode.md` § Phase 1). **If the bug CANNOT be reproduced, stop and report — do not guess-patch.**
2. **Phase 2 — Isolate Root Cause**: trace symptom → proximate cause → root cause (RCA template: `reference/bugfix-mode.md` § Phase 2); fixing a symptom → stop, go deeper; not found after 3 levels of indirection → pause and report, no surface-level patch. Then evaluate routing (below).
3. **Phase 3 — Write a Regression Test**: exercise the exact bug path with the failing inputs; it MUST fail with the bug's symptom NOW, before the fix (already passing → the test does not cover the bug, rewrite it; no failing test possible → most targeted test, marked `[flaky]`).
4. **Phase 4 — Fix**: minimum change resolving the root cause; one conceptual change per fix — no bundled refactoring, style changes, or "while I'm here" improvements (root cause in a different file → fix it there). Run the regression test (MUST pass) + relevant unit tests.
5. **Phase 5 — Self-Check & Report**: `bun typecheck`; `bun oxlint --deny-warnings`; `bun run test:changed` (all pass; full suite belongs to verify); verify `core/checklists/bugfix.md`; publish the bugfix report as wiki page `{slug}/bugfix-report` (template: `reference/bugfix-mode.md` § Bugfix Report); persist per the Phase 5 persistence rule (Mode: implement, [org-internal #2847]).
6. **Phase 5.5 — Issue Checklist Sync (standalone bugfix)**: sync the source issue at each transition (commit / PR / review / CI / close) per the `issue-checklist-sync` L1 rule and its standalone-flow table.
7. **Phase 6 — Approval**: present the report (prompt: `reference/bugfix-mode.md` § Phase 6 — Approval).
#### Routing Decision (after Phase 2)
Full escalate/stay criteria: `reference/bugfix-mode.md` § Routing Decision. In short — **escalate to pipeline** on ANY of: ≥ 5 files · ≥ 2 modules/components · design-level root cause · data migration / schema change · public-API / contract change · dependency change · > 50 lines · user requests full-process; **stay standalone** only when ALL the opposites hold. If uncertain, escalate — a false escalation costs review rounds; a false standalone decision skips quality gates.
**Big-bug relabel rule ([org-internal #3061])** — before the generic escalation above, split the triggers by kind:
- **Design-level triggers** (root cause is a design decision — protocol / schema / architecture; shared-contract or public-API change; data migration): do NOT push through bugfix — **relabel the ticket `Kind/Feature`** and reroute via Step 0 (DAG route; 1–3 node small DAG expected); repro + root-cause notes become node input.
- **Mechanical size triggers only** (many files / lines, same design): stay in bugfix — batch into iterations, keep review-code + verify. Scale alone never justifies a relabel.
#### Pipeline Mode (bugfix)
> **Legacy path retired ([org-internal #3072] phase 3)**: the requirements → design → review → plan front-end was archived; a big bug needing a design-level decision relabels `Kind/Feature` into the DAG route (big-bug relabel rule above).
When a bugfix escalates beyond standalone scope, the bug report becomes a pipeline input; the bugfix phases (reproduce, root cause, regression test, fix) are embedded within the implement stage, and review-code + verify remain mandatory. On the DAG route the node spec lives in `{epic-slug}/dag`; the Developer follows bugfix Phases 1–6 as the implementation method, then produces the standard implementation report (Mode: implement, Phase 5).
**Pipeline abort criteria** — before any code is written in pipeline mode, abort if ANY of: (1) bug no longer reproduces; (2) root-cause hypothesis falsified during re-isolation; (3) resolved by external change; (4) reproduction confidence < 3/5 after one re-isolation iteration. Abort procedure (`{slug}/ABORT` wiki page, no commit/merge, retrospective, archive): `reference/bugfix-mode.md` § Pipeline Abort Criteria. Once code is written, abort is no longer valid — the run proceeds review-code → verify.
**Common Rationalizations (bugfix) & Incident Triage** — full 9-row Excuse → Reality table + Incident Triage Carve-Out (under active incident pressure the Phase 2→3 ordering MAY be relaxed, never skipped — a stop-gap may ship first, BUT the full root-cause trace + failing regression test + proper fix MUST land in the same incident window): `reference/bugfix-mode.md` § Common Rationalizations (bugfix) / § Incident Triage Carve-Out.
---
<!-- section:mode-refactor -->
### Mode: refactor
Restructure existing code without changing observable behavior — the existing test suite is the safety net; every step MUST be verified before proceeding. Templates and prompts: `reference/refactor-mode.md` (read at mode entry). **Execution modes**: standalone (user says "refactor {X}"; review gate optional — only when > 50 lines or ≥ 5 files) vs pipeline (refactoring WI / DAG node; scope from the node spec, review mandatory).
#### Preconditions
- [ ] Scope is specified (which file, module, or pattern to refactor).
- [ ] An existing test suite covers the scope (if unknown, run with coverage first).
- [ ] No uncommitted changes (`git status` is clean); `core/checklists/refactoring.md` is accessible.
**No test coverage? Stop.** Refactoring without tests is rewriting with unknown side effects — write characterization tests first or skip this module (prompt: `reference/refactor-mode.md` § No Test Coverage? Stop.).
#### Phases skeleton
1. **Phase 1 — Scope & Baseline**: map exact files + dependents; run `bun run test:parallel` (the refactor baseline legitimately needs the full suite) — ANY pre-existing failure → stop ("Cannot begin refactoring with failing tests. Fix them first."). Capture baseline: test count, coverage, optional complexity (template: `reference/refactor-mode.md` § Baseline).
2. **Phase 2 — Define Target Pattern**: Extract / Inline / Rename / Move / Replace / Simplify / Upgrade, with one-sentence goal + success criteria (all tests pass unchanged; structural goal met; coverage does not decrease). Pipeline mode: align with the node spec + contracts, or justify in the report.
3. **Phase 3 — Decompose into Steps**: smallest individually-verifiable steps (each reversible, suite-passing, ONE conceptual transformation); present the plan before executing (user may approve / reorder / reject). **If > 10 steps, the scope is too large — split into multiple sessions.**
4. **Phase 4 — Incremental Execution**: per step — transform, run `bun run test:changed` (ALL pass; per-step scoped reruns — full suite is verify's job, [org-internal #2598]), commit `refactor: {what} from {where}`. **If FAIL: revert immediately** — do NOT fix the test or code within the same step; find a smaller decomposition (exception: fix a flaky test first as a prerequisite step, then retry).
5. **Phase 5 — Final Validation**: `bun run test:parallel` all pass; `bun typecheck` zero errors; `bun oxlint --deny-warnings` zero errors; coverage MUST NOT decrease vs baseline (±1% noise).
6. **Phase 6 — Report**: before/after metrics, steps executed, verification results, design deviations (template: `reference/refactor-mode.md` § Refactor Report).
7. **Phase 7 — Approval**: present the report (prompt: `reference/refactor-mode.md` § Phase 7 — Approval). Route to code review if > 50 lines or ≥ 5 files.
---
<!-- section:mode-port -->
### Mode: port
Port a feature from a source project into the current (target) project, preserving the source's behavioral contract while adapting every implementation detail to the target's tech stack and conventions. Orchestration, per-phase processes, and templates live in the existing `reference/*.md` port files (indexed in References); read `reference/port-mode.md` at mode entry.
**Tester focus (port)**: behavioral-fidelity tests — every `FID-*` item in `port-{name}/source-analysis/10-fidelity-baseline` MUST map to ≥ 1 ported test (rewrite the source test in the target framework's style, preserving the contract); port edge/error/boundary tests, not just the happy path (missing FID coverage is the #1 cause of incomplete porting); every `[FIDELITY DEVIATION]` gets a test locking the divergent behavior.
#### Phase 0 — Scope Assessment
Measure the source scope — file count and LOC alone are insufficient: (1) source files; (2) source LOC (exclude tests); (3) source modules / feature areas; (4) source packages touched; (5) implicit dependency artifacts (schema/migrations, config, env vars, CLI flags, theme files, routes, providers, build config — full list: Phase A1.8). Then:
- **Standalone** (Part 1): ≤ 5 files, ≤ 200 LOC, 1 package, 0 implicit deps.
- **Pipeline** (Part 2): > 5 files or > 200 LOC · spans ≥ 3 source modules · spans ≥ 2 packages · or ≥ 3 implicit dependency artifacts (implicit deps require capability boundary analysis).
Report the assessment and do NOT proceed without explicit approval (prompt: `reference/port-mode.md` § Phase 0 — Scope Assessment).
#### Preconditions
- [ ] Source project path/reference and source feature scope specified; target project structure accessible (all monorepo packages).
- [ ] Target is the current working directory, clean workspace, existing test framework (none → warn: behavioral fidelity cannot be guaranteed — `reference/port-mode.md` § Preconditions).
- [ ] Target's existing capabilities documented or discoverable (else run the structural survey, Phase A1.7, first); `core/checklists/port.md` is accessible.
#### Part 1 — Standalone Mode (Small Port)
The Developer executes the full port lifecycle directly; no DAG decomposition; **code review is mandatory regardless of size** (Phase A8). Phases: A1 source analysis → A1.5 review GATE → A1.7 target surface → A1.8 capability boundary GATE (`reference/source-analysis.md`) · A2 concept mapping → A3 gap analysis → A4 adaptation design (`reference/mapping-and-design.md`) · A5 implement + A5.5 self-check GATE (rules below) · A6 port tests & fidelity (`reference/fidelity-verification.md`) · A7 report (`reference/port-report-template.md`) · A8 approval → code review (`reference/port-mode.md` § Phase A8).
**Phase A5 — Implement (rules)**: one file at a time (port completely, verify, then move on); **target conventions are law**; **fidelity over aesthetics** — do not "improve" the source logic (port the exact validation, log `[NOTE: weak validation in source]`; stricter behavior is a separate feature item); port comments from source (translated); `bun typecheck` after each file; no new dependencies (use the adaptation-design alternative or reimplement the subset inline).
**Phase A5.5 — Self-Check GATE (MANDATORY)**: complete `core/checklists/port.md` in full — every item ☑ (pass) or ☐ (fail) with written justification; every ☐ item documents an inline fix plan; known deferrals include a reactivation path (chunk + trigger); publish as wiki page `port-{name}/self-check`. Do NOT proceed to Phase A6 until all items are ☑ OR all ☐ items have documented fix plans AND the Developer has printed `SELF-CHECK COMPLETE — {X} items passing, {Y} items deferred with plan`.
#### Part 2 — Pipeline Mode (Large Port)
The Developer produces a source analysis report as the foundation artifact, then the port flows through the pipeline with peer-review gates: `port (source analysis) → analyze-dag (decompose by source module) → review-dag single gate → per node (dag.task_route): implement → review-code → verify (integration + fidelity)`. Phases: B1 12-document source analysis → B1.5 10-dimensional review GATE → B1.7+B1.8 target surface & capability boundary artifacts → B2 checklist self-check → B3 handoff to analyze-dag (slug `port-{name}`) → B4 per-node DAG task route (`reference/large-port-pipeline.md`) · B5 verify — integration + fidelity, every `FID-*` traced to a passing test (`reference/fidelity-verification.md`) · B6 final approval (rules below).
**Phase B6 — Final Approval**: verify (1) CI is configured (absent → warn `[GAP: no CI — no automated gate before merge]`, flag in report); (2) all review gates passed (review-dag single gate + every node's code review `converged: true`); (3) typecheck + lint + tests pass fresh. Present the consolidated report (prompt: `reference/port-mode.md` § Phase B6). Post-merge cleanup: `reference/port-mode.md` § Phase B7.
---
<!-- section:pipeline-detection -->
## Pipeline Work Item Detection
Not all work items involve writing new code — some are refactoring, bugfix, or frontend work items. They use the workflows above (or the frontend skill) but flow through the same pipeline gates (review-code → verify; DAG-routed work resolves its spec from `{epic-slug}/dag`). When detected, read `reference/work-item-detection.md` BEFORE Phase 1 for the per-phase pipeline adaptations. Detection triggers (full keyword lists in the reference):
| Work item | Detected by (examples) | Route |
|---|---|---|
| **Refactoring** | "Refactor" / "重构" / "Extract" / "Rename" … prefixes; `[REFACTOR]` tag; behavior-preserving structural node spec; REQ-REFACTOR-* | Mode: refactor + adaptations — code review mandatory regardless of size, no "no review needed" bypass |
| **Bugfix** | "Bugfix" / "Fix" / "修复" / "Hotfix" prefixes; `[BUGFIX]` tag; correction-of-behavior node spec; bug report / stack trace / RCA reference | Mode: bugfix + adaptations — code review mandatory regardless of size |
| **Frontend** | "Frontend" / "UI" / "组件" / "页面" prefixes; `[FRONTEND]` tag; UI-layer node spec; components in `components/` `pages/` `views/` `ui/`; exclusively `.tsx`/`.jsx`/`.vue`/`.svelte`/`.astro`/`.css`/`.scss` files | `core/skills/frontend/SKILL.md` + adaptations — code review mandatory regardless of size |
## References
**On-demand mode references** (NOT injected — read at the declared timing):
- `reference/implement-mode.md` — Mode: implement: mode entry (phase detail); Phase 2 / Phase 5 templates; Tester focus; Common Rationalizations; legacy notes.
- `reference/bugfix-mode.md` — Mode: bugfix: mode entry; Phase 1–3 templates; Phase 5 report + publish; routing escalation; abort procedure; orchestration.
- `reference/refactor-mode.md` — Mode: refactor: mode entry; Phase 1 baseline; Phase 6 report; no-coverage stop prompt.
- `reference/port-mode.md` — Mode: port: mode entry; Phase 0 prompt; preconditions warnings; A8/B6 approval prompts; B7 cleanup.
- `reference/work-item-detection.md` — detected refactoring / bugfix / frontend work item: BEFORE Phase 1 of the matched mode.
- `core/checklists/implementation.md` — Implementation self-check checklist
- `core/checklists/bugfix.md` — Bugfix self-check checklist
- `core/checklists/refactoring.md` — Refactoring self-check checklist
- `core/checklists/port.md` — Porting self-check checklist
- `core/checklists/frontend.md` — Frontend self-check checklist
- `core/checklists/code-review.md` — Code review checklist (self-attestation)
- `core/checklists/pipeline-gate.md` — Cross-stage pipeline gate checklist
- `core/skills/frontend/SKILL.md` — Frontend workflow (for frontend work items)
- `core/skills/browser-debug/SKILL.md` — Interactive browser verification (for frontend work items) and UI bug reproduction (bugfix Phase 1)
- `core/skills/review-code/SKILL.md` — Code review (next step after implementation)
- `core/skills/verify/SKILL.md` — Integration + fidelity verification (pipeline-mode bugfix, large port)
- `<instance-root>/archive/skills/` — Legacy requirements/design/plan/roadmap skills (archived [org-internal #3072] phase 3; their templates moved to `<instance-root>/archive/templates/`)
- `reference/source-analysis.md` — Port Phase A1, A1.5, A1.7, A1.8 detailed processes & templates
- `reference/mapping-and-design.md` — Port Phase A2, A3, A4 detailed processes & templates
- `reference/large-port-pipeline.md` — Port Phase B1–B4 detailed processes
- `reference/fidelity-verification.md` — Port Phase A6, B5 detailed processes & templates
- `reference/source-analysis-templates.md` — Port B1 document format templates
- `reference/capability-boundary-template.md` — Port A1.8/B1.8 13-dimension table
- `reference/target-surface-template.md` — Port A1.7/B1.7 output format
- `reference/port-report-template.md` — Port A7/B6 report format
- Martin Fowler, _Refactoring: Improving the Design of Existing Code_ (2nd ed.)
- `core/rules/` — Project engineering conventions (test commands, typecheck)
- L2 wiki pages for style-guide, effect-rules, and database conventions (see the "L2 on-demand reference" section of AGENTS.md)
core/skills/implement/reference/bugfix-mode.md
+494
View File
@@ -0,0 +1,494 @@
> Extracted from implement/SKILL.md (Mode: bugfix) — moved verbatim 2026-08-25, ticket [org-internal #3381].
### Mode: bugfix
Reproduce, isolate, and fix a bug with a regression test to prevent
recurrence. For small, localized bugs, use standalone mode — the existing
system behavior is the specification. For large, complex bugs, route through
the full quality pipeline.
#### Process Overview
Every diamond below is a gate Developers rationalize skipping — especially
under "the bug is obvious" pressure.
```dot
digraph bugfix {
rankdir=TB;
node [shape=box, fontname="Helvetica"];
repro [shape=diamond, label="Bug reproduces?"];
norepro [label="STOP: report cannot-reproduce\n(do not guess-patch)"];
rc [shape=diamond, label="Root cause found\n(not just symptom)?"];
symptom [label="Go deeper — do NOT\npatch the symptom"];
route [shape=diamond, label="Routing:\nstandalone vs pipeline?"];
escalate [label="Uncertain → escalate\nto pipeline mode"];
rtest [shape=diamond, label="Regression test\nFAILS before fix?"];
notest [label="Test does not cover\nthe bug — rewrite it"];
fix [label="Phase 4: Fix\n(one change, root cause only)"];
green [shape=diamond, label="Regression test PASS\n+ full suite green?"];
done [shape=doublecircle, label="Phase 5/6:\nSelf-Check + Report"];
repro -> norepro [label="no"];
repro -> rc [label="yes"];
rc -> symptom [label="no"];
rc -> route [label="yes"];
route -> escalate [label="uncertain"];
route -> rtest [label="standalone"];
rtest -> notest [label="passes already"];
rtest -> fix [label="fails (confirmed)"];
fix -> green;
green -> fix [label="no: fix + re-run"];
green -> done [label="yes"];
}
```
#### Execution Modes
| Mode | Entry Point | Scope Source | Review Gate | Verify Gate |
| ---------- | -------------------------------------- | ------------------ | ------------ | ----------- |
| Standalone | User says "fix this bug" | Bug report + code | Optional (>20 lines or ≥3 files) | None |
| Pipeline | User requests full-process bugfix, or auto-escalation | Bug report → requirements → design → plan → implement | Mandatory | Mandatory |
> **Routing override (ticket-seeded)**: the Optional/None gate declarations
> above apply to *user-initiated* standalone mode. When the ticket carries a
> `Kind/*` route whose `keep_gates` includes `review-code` / `verify` (e.g.
> `Kind/Bug`, `Kind/Testing` — see `<instance-root>/workflow-routing.yaml`), those
> gates are MANDATORY regardless of size. Per `core/rules/workflow-routing.md`,
> a gate is mandatory if EITHER the route OR the skill requires it; skipping is
> valid only when BOTH agree it is skippable.
In pipeline mode, the bug report becomes a bugfix work item that flows through
the full requirements → design → plan → implement → review-code → verify
pipeline.
#### Role & Responsibilities
The bugfix is owned and executed by the **Developer** (Worker). The
Developer owns both implementation and bugfix — same role, same skill set.
The Developer is responsible for:
- Reproducing the bug from the description.
- Identifying the root cause (not just patching the symptom).
- Writing a regression test that fails before the fix and passes after.
- Applying the minimal surgical fix — one change, one purpose.
- Running the full test suite to confirm no regressions.
The Builder's role is to present the bugfix report and route it to code
review if the change is non-trivial (> 20 lines or touches ≥ 3 files).
#### Tester focus for bugfix
The Tester role in bugfix writes **regression tests** and, uniquely,
intervenes BEFORE the fix (a regression test must fail before the fix to
prove the bug exists):
- **Failing regression test** — read `repro-notes.md` (the Developer's
reproduction + root-cause analysis from Phases 1–2), write a test that
exercises the exact bug path and FAILS with the bug's symptom. This MUST
happen before Phase 4 (Fix), not after — it is Phase 3.
- **Passing confirmation** — after the Developer's fix, the same test MUST
pass (the Developer's green run in Phase 4 verifies this).
- **Boundary regression tests** — inputs adjacent to the bug trigger,
similar conditions that must NOT trigger the fix (guards against
over-fixing), and error paths near the root cause.
**Bugfix-specific orchestration** (overrides the standard role-split flow):
Because a regression test must fail BEFORE the fix, the bugfix role split
inverts the standard orchestration — the Tester dispatches between
Phase 2 and Phase 4, not after the fix:
```
[Worker: developer] Phase 1 reproduce + Phase 2 root cause
→ write repro-notes (reproduction steps, root cause, bug path,
expected behavior)
↓ persist: wiki page `{slug}/repro-notes` (gitea_wiki__create_page)
[Worker: tester] read repro-notes → Phase 3 write failing regression test
(confirms FAIL before fix)
↓ persist: wiki page `{slug}/test-report` (gitea_wiki__create_page, failing test confirmed)
[Worker: developer] Phase 4 fix → run test:changed to green
→ write impl-notes (post-fix behavior contract)
↓ persist: wiki page `{slug}/impl-notes` (gitea_wiki__create_page, post-fix behavior contract)
[Worker: tester] supplement boundary regression tests → run test:changed
↓ persist: update wiki page `{slug}/test-report` (gitea_wiki__update_page, final)
— consumed by the human stakeholder / next iteration planning for DoD regression-test evidence
```
For small, single-file bugfixes with an obvious fix, a single Developer
Worker may write the failing test, fix, and confirm green in one invocation
— the split is optional for trivial fixes (Phase 3 + Phase 4 in one
session). Force the split when the fix touches ≥ 2 files or the root cause
spans ≥ 2 levels of indirection.
Pipeline-mode bugfixes route through the implement pipeline (see ### Mode:
implement (default)), with the bugfix-specific Tester focus above layered
on top of the standard role-split orchestration.
---
#### Preconditions (standalone)
Before starting the bugfix, confirm:
- [ ] Bug description exists (user's message, issue tracker link, or error log).
- [ ] Existing codebase is accessible.
- [ ] `core/checklists/bugfix.md` is accessible.
If the user describes a symptom without specifics, ask for:
```
To fix this bug, I need:
1. What is the expected behavior? (what should happen)
2. What is the actual behavior? (what happens instead)
3. Steps to reproduce.
4. Any error messages, logs, or stack traces.
```
---
#### Routing Decision
After Phase 1 (reproduce) and Phase 2 (root cause), the Developer evaluates
whether the fix qualifies for standalone or pipeline mode:
**Escalate to pipeline mode when ANY of:**
| Condition | Reason |
| --------------------------------------------------- | ------------------------------------------------------------ |
| Fix touches ≥ 5 files | Cross-file changes need design review and integration tests |
| Fix spans ≥ 2 modules / components | Multi-module fixes need architectural validation |
| Root cause is in a design-level decision (protocol, schema, architecture) | Design change needs requirements + design review |
| Fix requires data migration or schema change | Schema changes need data design review and migration plan |
| Fix changes a public API or interface contract | API changes need interface design review and compatibility check |
| Fix introduces a new dependency or changes an existing one | Dependency changes need review (DGN dimension, code review) |
| Estimated lines changed > 50 | Large change carries high regression risk |
| User explicitly requests full-process bugfix | User wants quality gates |
**Stay in standalone mode when ALL of:**
| Condition |
| ---------------------------------------------- |
| Fix is ≤ 4 files |
| Fix is ≤ 1 module / component |
| Fix is a logic error, not a design error |
| No data migration or schema change |
| No API or interface contract change |
| No dependency change |
| Estimated lines changed ≤ 50 |
If the Developer is uncertain, escalate. A false pipeline escalation costs a few
extra review rounds. A false standalone decision risks missing a quality gate on
a complex change.
**Big-bug relabel rule ([org-internal #3061])** — before the generic escalation below, split
the triggers by kind:
- **Design-level triggers** (root cause is a design decision — protocol /
schema / architecture; shared-contract or public-API change; data
migration): do NOT push through bugfix and do NOT run the legacy pipeline
escalation — **relabel the ticket `Kind/Feature`** and reroute via Step 0
(DAG route; a 1–3 node small DAG is the expected shape for a single
design-level fix). The fix work already done (repro notes, root cause)
becomes node input, not wasted work.
- **Mechanical size triggers only** (many files / many lines, same design):
stay in bugfix — batch the change into iterations and keep the
review-code + verify gates. Scale alone never justifies a relabel.
When escalating, the Developer pauses after Phase 2, reports the routing
decision, and asks the user to confirm pipeline escalation:
```
This bugfix qualifies for pipeline mode:
- {N} files across {M} modules
- Root cause: {design-level issue}
- Estimated lines: {N}
→ Route through requirements → design → plan → implement → review → verify?
(yes / no — proceed with standalone)
```
---
#### Phase 1 — Understand & Reproduce
1. **Read relevant code** — find the module/component likely responsible for
the bug. Use `grep` for error messages, `glob` for related files.
2. **Check existing tests** — do existing tests cover this code path? If a
test exists but passes, the bug is in the test or in an uncovered branch.
3. **Reproduce** — run the relevant test(s) or manually trigger the bug.
Confirm the actual behavior matches the bug report. Document the
reproduction:
```markdown
## Reproduction
**Steps**:
1. {step}
2. {step}
**Expected**: {what should happen}
**Actual**: {what happens}
```
4. If the bug CANNOT be reproduced, stop and report:
```
Cannot reproduce the bug. Here's what I tried:
- {step 1}
- {step 2}
→ Is the environment different? Are there missing steps? Does a specific
data state trigger it?
```
---
#### Phase 2 — Isolate Root Cause
Trace from the symptom to the root cause:
1. **Symptom**: surface-level error (e.g. "500 on login").
2. **Proximate cause**: the code that throws or returns wrong (e.g. "password
hash comparison returns false for valid password").
3. **Root cause**: the underlying defect (e.g. "password hashing config changed
in commit abc123 but the stored hashes were not re-hashed").
```markdown
## Root Cause Analysis
**Symptom**: {error message or wrong behavior}
**Proximate cause**: {file}:{line} — {what the code does wrong}
**Root cause**: {underlying defect — config, data, logic, or assumption}
**Introduced in**: {commit hash or version if known}
```
**Rules**:
- If you're fixing a symptom (e.g. adding a null check where the real bug is
that null should never reach that line), stop and go deeper.
- If you can't find the root cause after examining 3 levels of indirection,
pause and report findings. Do NOT apply a surface-level patch.
- **After Phase 2, evaluate the routing decision** (see Routing Decision table
above). If the fix qualifies for pipeline mode, pause and present the
escalation prompt before proceeding to Phase 3.
---
#### Phase 3 — Write a Regression Test
Before fixing, write a test that proves the bug exists:
1. Write a test that exercises the bug path with the failing inputs.
2. Run the test — it MUST fail with the bug's symptom.
3. The test must be specific: test the exact condition that was broken, not
a general "endpoint returns 200" test.
```markdown
## Regression Test
- **File**: {path to test file}
- **Test name**: {test function name}
- **What it verifies**: {the expected behavior that was broken}
- **Fails before fix**: ✅ (confirmed)
```
**Rules**:
- If you cannot write a test that fails (bug is non-deterministic, environment-
specific), write the most targeted test you can and mark it `[flaky]`.
- The test must fail NOW, before you apply the fix. If it passes already, the
test does not cover the bug.
---
#### Phase 4 — Fix
Apply the minimum change that resolves the root cause:
1. **One conceptual change per fix** — do not bundle a bugfix with refactoring,
style changes, or "while I'm here" improvements.
2. **Fix the root cause**, not the symptom. If the root cause is in a different
file than the symptom, fix it there.
3. **Update only what's necessary** — if fixing a null-safety bug requires
adding a null check in one place, add one null check, not a comprehensive
null-safety overhaul of the entire module.
4. Run the regression test — it MUST pass.
5. Run the relevant unit tests — all existing tests must still pass.
---
#### Phase 5 — Self-Check & Report
##### Self-Check
1. **Typecheck**: `bun typecheck` — zero errors.
2. **Lint**: `bun oxlint --deny-warnings` — zero errors.
3. **Full test suite**: `bun run test:parallel` — all tests pass (new + existing).
4. **Checklist**: verify every item in `core/checklists/bugfix.md`.
5. **Publish bugfix report**: write the bugfix report as a wiki page via `wiki 读写 API（见 TERMINOLOGY）` with page_name `{slug}/bugfix-report` (`_shared/gitea-write-patterns.md` Pattern 1).
##### Report
```markdown
## Bugfix Report
**Bug**: {one-line description}
**Root cause**: {file}:{line} — {explanation}
**Fix**: {file} — {single-sentence description of change}
**Lines changed**: {N}
**Regression test**: {test file}:{test name}
### Verification
- Regression test: {PASS | FAIL}
- Full test suite: {N} passed, 0 failed
- Typecheck: ✅
- Lint: ✅
### Files Changed
| File | Lines | Purpose |
| ------------------- | ------ | ------------------------------------------------------ |
| `src/auth/login.ts` | +3, -1 | Fix password hash comparison when salt version changes |
---
**Handoff**: {if changes > 20 lines or ≥ 3 files → run `core/skills/review-code/SKILL.md`
| otherwise → fix complete, no review needed}
> **Routing override**: when the ticket carries a `Kind/*` route whose
> `keep_gates` includes `review-code` / `verify` (e.g. `Kind/Bug`,
> `Kind/Testing`), those gates are MANDATORY even for small fixes — the
> "no review needed" branch above does not apply (see the Execution Modes
> routing-override note above).
```
---
#### Phase 5.5 — Issue Checklist Sync (standalone bugfix)
In standalone-bugfix mode there are no skill-exit boundaries between commit,
PR, review, and CI — without explicit sync points the issue goes stale. Per
the `issue-checklist-sync` L1 rule, sync at each externally visible
transition (skip any step if no source issue exists):
| When | Sync action |
|------|-------------|
| After the fix commit | Check off fix-delivered ACs with `_(commit {sha}: file)_` |
| After PR creation | Ensure the `## 当前状态` section exists (the PR row is auto-written by the status-sync poller — see `issue-checklist-sync.md` § Automated sync) |
| After review convergence | Review-related ACs get `_(reviewed: round N PASS)_` (done by review-code Phase E 2.7) |
| On CI state transitions | Update process-AC progress (e.g. "N consecutive green") with run number |
| At verify PASS / close | Final sweep per `verify` Phase 5.6 |
Bugfix mode delegates the "after commit" step to the same mechanics as Phase
4.6 above (fetch issue body → map `- [ ]` items → `工单 API（见 TERMINOLOGY）update`), and
the PR-creation step to Phase 4.7.
---
#### Phase 6 — Approval
Present the report:
```
Bug fixed: {one-line description}
- Root cause: {file}:{line}
- {N} lines changed in {M} files
- Regression test added: {test name}
- Full test suite: ✅
→ {if review needed: "Run code review?" | else: "Fix complete. Approve?"}
```
---
#### Common Rationalizations (bugfix)
Bugfixes fail from **pressure and false confidence** far more than from
ignorance — "the bug is obvious" is the thought that precedes a symptom patch,
a bundled diff, or a regression that surfaces weeks later. These are the
excuses that precede every reopened bug. If you catch yourself thinking any
row's "Excuse", stop: the "Reality" column is the exact rule you are about to
break.
| Excuse | Reality (the rule being broken) |
|--------|---------------------------------|
| "Just add a null check where it crashes" | Symptom-patching. Phase 2: if you are fixing a symptom, stop and go deeper — the real defect is whatever let null reach that line. |
| "Can't reproduce, but I'm sure it's X" | Phase 1: if the bug cannot be reproduced, stop and report. Guess-patching a non-reproduced bug fixes nothing verifiable. |
| "3 levels deep, can't find it, patch the symptom" | Phase 2: after 3 levels of indirection with no root cause, pause and report — do NOT apply a surface patch. |
| "Bug's obvious, I'll fix then add the test" | Phase 3: the regression test MUST fail before the fix. Fix-first means you test your fix, not the bug. |
| "Test passed immediately, ship it" | Phase 3 Rules: a test that passes before the fix does not cover the bug — rewrite it until it fails. |
| "While I'm in this file, also clean up…" | Phase 4 rule 1: one conceptual change per fix. Bundling refactors/style/other-fixes pollutes the regression signal. |
| "Make the whole module null-safe while I'm here" | Phase 4 rule 3: update only what is necessary. Over-fixing turns a 3-line surgical fix into a high-risk diff. |
| "Fix is isolated, skip the full suite" | Phase 4 rule 5 + Phase 5: the full suite catches regressions your isolated view cannot. |
| "4 files but one module, standalone's fine" | Routing Decision: escalate when uncertain. A false-standalone call skips quality gates on a complex change. |
##### Incident Triage Carve-Out
When the bugfix occurs under **active production incident** pressure
(user-facing outage, on-call escalation), the Phase 2→3 ordering can be
**temporarily relaxed** — but never skipped:
1. A stop-gap (symptom patch) MAY ship first to restore service.
2. BUT the full root-cause trace + failing regression test + proper
root-cause fix MUST land in the **same incident window** — never deferred
to "tomorrow" or "a follow-up ticket".
3. If you defer, you have not fixed the bug — you have shipped a symptom patch
with a promise. Promises are not regression tests.
This carve-out exists because the rationalization table above cannot resolve a
*legitimate* priority conflict (service down vs process discipline). It
resolves it by permitting triage but forbidding deferral.
---
#### Pipeline Mode (bugfix)
> **Legacy path retired ([org-internal #3072] phase 3, 2026-08-21)**: the full
> requirements-elicitation → design → review-artifact(design-space) →
> plan-iterations → review-artifact(plan) front-end was archived
> (`<instance-root>/archive/skills/`). A big bug that needs a design-level decision
> now relabels `Kind/Feature` and enters the DAG route (see the big-bug
> relabel rule above) — repro + root-cause notes carry over as node input.
> The abort criteria below still apply to any multi-stage bug run before
> code is written.
When a bugfix escalates beyond standalone scope, the bug report becomes a
pipeline input; the original bugfix phases (reproduce, root cause, regression
test, fix) are embedded within the implement stage, and review-code + verify
remain mandatory gates.
##### Pipeline Abort Criteria
Before any code is written in pipeline mode, abort the pipeline if ANY of:
| # | Condition | Action |
|---|-----------|--------|
| 1 | Bug no longer reproduces after environment change (strace re-isolation returns 0 reproductions, user confirms symptom resolved) | Write ABORT to wiki page `{slug}/ABORT` (wiki 读写 API（见 TERMINOLOGY）), preserve all completed artifacts, run retrospective |
| 2 | Root cause hypothesis is falsified during re-isolation (e.g., strace shows suspected git spawn is NOT hanging) | Write ABORT.md, escalate to Architect for design revision OR abort pipeline |
| 3 | Bug is resolved by external change (new binary build, dependency update, OS/kernel patch) | Write ABORT.md with resolution evidence, close without code changes |
| 4 | Reproduction confidence < 3/5 after re-isolation attempt | Write ABORT.md if confidence cannot be improved within 1 re-isolation iteration |
**Abort procedure**:
1. Write ABORT to wiki page `{slug}/ABORT` (wiki 读写 API（见 TERMINOLOGY）) documenting the reason, evidence, and which artifacts are preserved.
2. Do NOT commit or merge the bugfix branch (no code was written).
3. Run retrospective to extract process improvements.
4. Archive artifacts to wiki page `_archive/{slug}/` (wiki 读写 API（见 TERMINOLOGY）) after retrospective.
**Scope**: these criteria apply before the implement stage. Once code is written, the pipeline proceeds through review-code → verify — abort is no longer valid.
##### Stage: Implement → Code Review → Verify
On the DAG route a bug-fix node's spec (ACs tracing to the repro + root cause)
lives in `{epic-slug}/dag`; the Developer follows the bugfix Phases 1–6 (from
standalone mode above) as the implementation method, then produces the
standard implementation report (see ### Mode: implement (default), Phase 5).
Code review runs all 10 dimensions against the bugfix changes. Verify runs
the full DoD matrix including regression tests, integration tests, and NFR
validation. Output pages: code review → `{slug}/reviews/code/final/report`;
verification → `{slug}/05-verify-iteration-1`.
core/skills/implement/reference/capability-boundary-template.md
+76
View File
@@ -0,0 +1,76 @@
# Capability Boundary — Dimension Table & Output Template
> Used by Phase A1.8 (standalone) and Phase B1.8 (pipeline).
> Read this file when executing the Capability Boundary Definition phase.
> The 13-dimension table defines WHAT to analyze; the output template defines
> HOW to record it.
## Artifact Dimensions
Every capability MUST be analyzed across ALL of these dimensions. A dimension
with no artifacts is explicitly marked "N/A — none required" (not silently
skipped):
| # | Dimension | What to list | Why it matters |
|---|-----------|-------------|----------------|
| 1 | **Source code files** | Every .ts/.tsx/.js file in the feature scope | The obvious one — but not the only one |
| 2 | **Type definitions / interfaces** | Shared types, branded types, schemas (Zod/Schema.Class) | Types are consumed across files; missing types break compilation silently |
| 3 | **Database schema / migrations** | Table definitions, column additions, migration SQL | Data layer changes are invisible in code diffs but block runtime |
| 4 | **Configuration entries** | Config keys, settings entries, default values | Missing config = silent runtime failures |
| 5 | **Environment variables** | Env vars read by the feature, VITE_* vars | Missing env vars = undefined behavior at runtime |
| 6 | **CLI flags / commands** | CLI commands, flags, option definitions | CLI surface changes are easily forgotten |
| 7 | **Theme / style files** | CSS files, theme JSON, tailwind config, token files | Styling is per-component and easily orphaned |
| 8 | **Route definitions** | New routes, modified redirects, route guards | Routes are defined in a central file far from the feature code |
| 9 | **Provider / context hierarchy** | New providers, insertion points in provider tree, context keys | Provider ordering bugs are silent and hard to debug |
| 10 | **Build config changes** | vite.config, tsconfig, webpack, tailwind.config | Build config gates whether the feature compiles/bundles |
| 11 | **Package.json dependencies** | New npm deps, version changes, workspace dep additions | Missing deps = import errors at runtime |
| 12 | **Test files** | Unit tests, integration tests, test fixtures, test helpers | Tests are the fidelity contract — missing tests = unverified behavior |
| 13 | **Shared package changes** | Changes to SDK, UI, core packages that the feature depends on | Cross-package deps are the #1 source of incomplete ports |
## Output Template
Publish to wiki page `port-{name}/source-analysis/capability-boundary` (standalone) or
`port-{name}/source-analysis/12-capability-boundary` (pipeline) via `wiki 读写 API（见 TERMINOLOGY）`.
```markdown
## Capability Boundary: {feature name}
### Dimension 1 — Source Code Files
| Source File | Target Location | Status | Notes |
| ----------- | --------------- | ------ | ----- |
| src/context/tabs.tsx | src/context/tabs.tsx | ☐ | New file |
| ... | ... | ... | ... |
### Dimension 2 — Type Definitions / Interfaces
| Source Type | Target Location | Status | Notes |
| ----------- | --------------- | ------ | ----- |
| Tab interface | src/context/tabs.tsx | ☐ | Co-located |
| ... | ... | ... | ... |
### Dimension 3 — Database Schema / Migrations
| Source Schema | Target Migration | Status | Notes |
| ------------- | ---------------- | ------ | ----- |
| N/A — none required | — | ⏭ | Feature uses in-memory state only |
### Dimension 4 — Configuration Entries
| Source Config Key | Target Config Key | Status | Notes |
| ----------------- | ----------------- | ------ | ----- |
| tabs.enabled | tabs.enabled | ☐ | New setting |
| ... | ... | ... | ... |
### Dimension 5 — Environment Variables
| Source Env Var | Target Env Var | Status | Notes |
| -------------- | -------------- | ------ | ----- |
| VITE_TABS_LIMIT | VITE_TABS_LIMIT | ☐ | New |
| N/A | — | ⏭ | No env vars required |
(... repeat for all 13 dimensions ...)
### Completeness Cross-Check
| Cross-Check | Result |
| ----------- | ------ |
| Every A1 Source Function Inventory item appears in D1 or D2? | ✅ / ❌ |
| Every A1.7 Structural Diff gap has a capability boundary entry? | ✅ / ❌ |
| All 13 dimensions filled in? | ✅ / ❌ |
| All ☐ items have deferral + reactivation path or are pre-implementation? | ✅ / ❌ |
```
core/skills/implement/reference/fidelity-verification.md
+77
View File
@@ -0,0 +1,77 @@
# Fidelity Verification — Detailed Processes
> Extracted from `implement/SKILL.md` (Mode: port) Phase A6 and B5.
> Read this file when executing the test porting and fidelity verification phases.
---
## Phase A6 — Port Tests & Verify Fidelity
1. **Port every test** from the source — not just the happy path. Edge cases,
error paths, and boundary tests must all be ported.
2. **Rewrite assertions** to match the target test framework's assertion style.
3. **Run ported tests** — they must pass. If a test fails:
- Behavior mismatch: fix the implementation to match source behavior.
- Test logic error (e.g. wrong assertion library syntax): fix the test.
- Infrastructure gap (e.g. test tried to connect to Redis): adapt the test
to the alternative from Phase A4.
4. **Full test suite** — run the target project's existing tests + ported
tests. No regression in existing tests.
5. **Fidelity checklist** — for each source behavior, verify manually or
automatically:
### Fidelity Verification Template
```markdown
## Fidelity Verification
| Source Behavior | Tested? | Result | Notes |
| --------------------------------- | ------------- | ------ | -------------------------------------------- |
| User login with valid credentials | ✅ ported | PASS | |
| User login with invalid password | ✅ ported | PASS | |
| Session expiry at 1h | ✅ ported | PASS | Adapted to DB session store |
| Rate limiting: 5 attempts / min | ⚠️ not ported | — | Target has no rate limiting infra → deferred |
```
---
## Phase B5 — Verify (Integration + Fidelity)
After all chunks are implemented and reviewed, run
`core/skills/verify/SKILL.md` with the fidelity baseline
(wiki page `port-{name}/source-analysis/10-fidelity-baseline`, read via `wiki 读写 API（见 TERMINOLOGY）`) as the
acceptance criteria:
- Every `FID-*` item must be traced to a passing test in the target project.
- Full test suite (existing + ported) must pass with no regressions.
- Typecheck and lint must be clean.
- Fidelity deviations from any chunk are consolidated into a final
fidelity report.
- **Reverse coverage (Ported? audit)**: The Source Function Inventory
(produced in Phase A1 / B1) "Ported?" column must have **zero** unexplained
☐ entries. Any residual ☐ MUST carry a matching `[DEFER]` row — with a
reactivation trigger — in the Port Fidelity Report. A bare ☐ is a FAIL,
not a deferral. This closes the #1 port-completeness gap: functions that
were never ported and never consciously deferred.
- **Symbol-level completeness (SRC-CMP)**: Run an automated export-symbol
diff between source and target packages. Every source symbol absent from
the target MUST appear as `[DEFER]` in the report; a silent gap is a FAIL.
```bash
diff <(codegraph exports <source-pkg>) <(codegraph exports <target-pkg>)
# Each left-only symbol must be DEFER'd or ported — silent gaps fail B5.
```
### Port Fidelity Report Template
```markdown
## Port Fidelity Report
| FID-* | Behavior | Chunk | Target Test | Status |
| ------- | ------------------ | ----------- | -------------------- | ------ |
| FID-001 | Login valid creds | chunk-auth | auth/login.test.ts | PASS |
| FID-002 | Login invalid pw | chunk-auth | auth/login.test.ts | PASS |
| FID-004 | Rate limiting | chunk-auth | — | DEFER |
**Summary**: {X}/{Y} behaviors verified, {Z} deferred
```
core/skills/implement/reference/implement-mode.md
+592
View File
@@ -0,0 +1,592 @@
> Extracted from implement/SKILL.md (Mode: implement) — moved verbatim 2026-08-25, ticket [org-internal #3381].
### Mode: implement (default)
The standard implementation workflow for work items from an approved
iteration plan. Implement a single work item, guided by the approved design,
and self-verify before passing to code review.
#### Pre-flight
The pre-flight self-check prompt format ([org-internal #2599]), prepended to the Developer
sub-agent's task prompt when `routes.{Kind}.preflight` is non-empty:
```
Pre-flight self-check (evidence-based, from retrospective — verify each
BEFORE writing code; if one is already satisfied, note why in impl-notes):
1. {item} (evidence: {evidence})
2. ...
```
#### Process Overview
Every diamond below is a gate agents rationalize skipping. None are optional.
```dot
digraph implement {
rankdir=TB;
node [shape=box, fontname="Helvetica"];
pre [shape=diamond, label="Preconditions\n(artifacts + reviews\nconverged)?"];
abort [label="ABORT: list every\nmissing item"];
p1 [label="Phase 1: Parse Context"];
p2 [label="Phase 2: Plan\n(≤3 files per WI)"];
scope [shape=diamond, label="Scope ≤3 files\nAND maps to a\ndesign component?"];
gap [label="Flag design gap,\nDO NOT invent decisions"];
p3 [label="Phase 3: Implement\n(design-exact, tests cover AC)"];
p4 [label="Phase 4: Self-Check\n(typecheck + lint +\ntest:changed + review checklist)"];
clean [shape=diamond, label="0 BLOCKERs\nand 0 MAJORs?"];
p5 [label="Phase 5: Report\n(AC → test traceability)"];
p6 [shape=doublecircle, label="Phase 6: Handoff\nto review-code"];
pre -> abort [label="no"];
pre -> p1 [label="yes"];
p1 -> p2;
p2 -> scope;
scope -> gap [label="no"];
scope -> p3 [label="yes"];
p3 -> p4;
p4 -> clean;
clean -> p4 [label="no: fix + re-run"];
clean -> p5 [label="yes"];
p5 -> p6;
}
```
#### Tester focus for implement
The Tester role in implement writes **boundary + contract tests**:
- **Contract tests** — for every public API signature in `impl-notes.md`,
verify the documented inputs/outputs, error paths, and side effects.
Each acceptance criterion (node `acceptance_criteria` in `{epic-slug}/dag`;
historically `04-plan-05-acceptance-criteria`) MUST map to at least one
test.
- **Boundary tests** — empty values, malformed input, permission
boundaries, concurrency edges, and the edge cases the node spec's decision
tables / state machines imply.
- **Failure-path tests** — every error scenario the node's cross-session
edge contracts (historically the interface design,
`03-design-04-interface-design`) specify.
The Developer's Phase 4 self-check (`bun run test:changed` to green) covers
the happy path and existing tests; the Tester's job is the cases the
Developer is structurally biased to miss.
#### Preconditions
> **Publish target (tiered targeting retired, [org-internal #3072] phase 3)**: the
> `Size/*`-tiered publish rule (`rules/workflow-routing.md` §"Publish target
> by Size/* tier — RETIRED") was retired with the legacy producer skills.
> Artifacts publish where the live mode puts them: DAG task mode → node spec
> in the frozen `{epic-slug}/dag` copy (see the DAG-mode input path below);
> standalone bugfix → `{slug}/bugfix-report` + issue body per bugfix Phase 5.
> Legacy tiered locations (`{slug}/02-03-req-design`, `{slug}/04-plan-*`, …)
> stay readable for historical runs via `_shared/gitea-read-patterns.md`.
> **DAG-mode input path** (DAG ticket pipeline — `Kind/Epic` / `Kind/Feature`
> DAG parent, routes-table direct):
> DAG-routed tickets **ignore `Size/*`** (`core/skills/analyze-dag/SKILL.md`).
> When the ticket routes through the DAG pipeline, the tiered Preconditions
> below are replaced by the node spec: the work item and its acceptance
> criteria resolve from the **frozen DAG copy** wiki page `{epic-slug}/dag`
> (and the `{epic-slug}/dag-nodes/{node-id}` subpages when AC detail is sunk)
> plus the node ticket's issue body — there is no `{slug}/04-plan-*` page and
> no `Size/*`-tiered req/design page. The design-space + iteration-plan review
> convergence preconditions are replaced by the **review-dag single-gate
> convergence**: `octopus review status --stage review-dag` must show state
> `success` before the node is implemented.
> **DAG-route read map** (applies to Phase 1 read inputs and the Phase 3/4
> artifact references below — mirror `verify/SKILL.md`'s DAG branch): when
> DAG-routed, resolve each legacy tiered artifact reference (any mention below
> of `{slug}/04-plan-*` / `{slug}/03-design-*` pages) from the frozen
> DAG copy instead:
>
> - Work item — `{slug}/04-plan-04-iteration-assignment` / issue body → the
> node spec in `{epic-slug}/dag` + the node ticket's issue body.
> - Acceptance criteria — `{slug}/04-plan-05-acceptance-criteria` / issue body
> → the node `acceptance_criteria` in `{epic-slug}/dag` (+
> `{epic-slug}/dag-nodes/{node-id}` subpages when AC detail is sunk) + the
> node ticket's issue body.
> - `test_id` (測試用例 ID) declared in `04-plan-05-acceptance-criteria` → the
> `test_id` declared on the node AC in `{epic-slug}/dag`.
> - Design sections — `{slug}/03-design-**` / `{slug}/02-03-req-design` → the
> node spec + cross-session edge contracts in the frozen DAG copy (design
> detail is folded into node AC + contracts; there is no `{slug}/03-design-*`
> page).
> - Interface design — `03-design-04-interface-design` → the node's
> cross-session edge contracts in `{epic-slug}/dag`.
> - Component mapping — `{slug}/03-design-08-traceability` → the node
> `req_refs` + component field in `{epic-slug}/dag`.
>
> At Phase 6 handoff, pass `mode: "dag-task"` to review-code (its DAG Task
> Mode keys off the same frozen-DAG-copy detection).
Before starting implementation, confirm:
> **Legacy pipeline preconditions retired ([org-internal #3072] phase 3, 2026-08-21)**: the
> tier-dependent requirements/design/plan artifact-existence checks and the
> design-space / iteration-plan review-convergence checks that used to head
> this list belonged to the archived legacy pipeline (`<instance-root>/archive/`).
> Live input modes: DAG task mode (node spec from the frozen
> `{epic-slug}/dag` copy — see the DAG-mode input path above; convergence
> precondition = `octopus review status --stage review-dag` shows `success`)
> and standalone modes (bugfix / refactor / port — the request itself is the
> spec). Historical req/design/plan pages stay readable via
> `_shared/gitea-read-patterns.md`.
- [ ] Work item is specified (DAG node ticket `{node-id}`, or a clear task
description in standalone modes).
- [ ] `core/checklists/implementation.md` is accessible.
- [ ] `slug` matches the run's slug (DAG: `{epic-slug}`).
- [ ] 跨阶段门控清单: `core/checklists/pipeline-gate.md` is accessible and
its DAG 路由变体 section has been confirmed item by item. Specifically:
the frozen DAG copy exists and the single gate has converged; the
node's cross-session upstream dependencies are at terminal state
(`ready`). If any dependency is not complete → abort, listing the
blocked nodes.
**If any precondition is unmet, abort and inform the user.** Refer to
`core/checklists/pipeline-gate.md` for the complete gate checklist. List
every missing artifact, every un-converged review, and every blocked dependency
explicitly so the user knows exactly what upstream work remains before
implementation can begin. Refer to the Recovery Protocol in
`core/checklists/pipeline-gate.md` to determine the recovery action for
each missing item.
#### Work-item selection
When the user requests implementation without specifying a work item, resolve
the work-item list from the frozen DAG copy: the ready/pending task nodes in
`{epic-slug}/dag` (via `wiki 读写 API（见 TERMINOLOGY）`), cross-checked against the
node tickets on the Epic's `## DAG 状态` table. (Legacy tier-based resolution
via `{slug}/04-plan-04-iteration-assignment` was archived 2026-08-21,
[org-internal #3072] phase 3.) Present the current ready nodes for selection:
```
Current iteration: Iteration {N}: {Goal}
Available work items:
| Work Item | Description | Complexity | Status |
|-----------|-------------|------------|--------|
| WI-001 | ... | 3 | PENDING |
| WI-002 | ... | 2 | PENDING |
→ Which work item should be implemented?
```
---
#### Phase 1 — Parse Context
> **Pipeline stage**: if the source issue exists, move it to the `implement`
> column on the Pipeline Stages board per `_shared/gitea-write-patterns.md`
> Pattern 7.5. Skip if no source issue exists.
Read the upstream artifacts to build a complete implementation context.
Resolve inputs per the DAG-route read map (Preconditions above); standalone
modes read the request/bug report instead:
1. **Work item** — the node spec in `{epic-slug}/dag` (+ the
`{epic-slug}/dag-nodes/{node-id}` subpage when detail is sunk) and the
node ticket's issue body:
- Node id, title, complexity (`size_attrs`).
- Requirements covered (`req_refs`).
- Component(s) involved (node component field).
2. **Acceptance criteria** — the node `acceptance_criteria` in
`{epic-slug}/dag` (+ sunk subpages) and the node ticket's issue body:
- Every falsifiable AC (`AC-{n}`) and `NFR:` entry.
- The declared 测试用例 ID (`test_id`) for each criterion — these drive the
Red → Green test-first order in Phase 3 and are the handshake with `verify`
(DOD-1.6).
3. **Design context** — the node spec + the node's cross-session edge
contracts in the frozen DAG copy (design detail is folded into node AC +
contracts; there is no separate design page). Historical
`{slug}/03-design-*` pages from legacy runs stay readable.
4. **Existing codebase** — use `glob` and `grep` to locate:
- Existing files in the component's directory.
- Existing tests.
- Existing type definitions, schemas, configuration files the work item
touches.
**Output**: internal only. The Developer MUST have read every referenced
design file before writing a single line of code.
---
#### Phase 2 — Plan Implementation
Before writing code, produce a brief implementation plan:
```markdown
## Implementation Plan: {WI-ID}
**Work item**: {description}
**Files to create**:
- `path/to/new/file.ts` — {purpose}
**Files to modify**:
- `path/to/existing/file.ts` — {what changes, why}
**Design compliance**:
- Component: {COMP-XXX} from {design-file}
- Interface: {iface-name} from {design-file}
- Data entity: {entity-name} from {design-file}
**Acceptance criteria to satisfy**:
- [ ] {criterion 1}
- [ ] {criterion 2}
```
**Rules**:
- If the implementation plan reveals that the work item touches > 3 files,
pause and ask: "This work item spans {N} files. Is the scope correct, or
should it be split?" The Builder (or user) MUST split it into smaller
work items each touching ≤ 3 files before proceeding.
- If the work item requires a file that doesn't map to any design component,
flag a design gap and abort. Do NOT invent design decisions.
Present the plan to the user:
```
Implementation plan for {WI-ID}:
- {N} files to create, {M} files to modify
- {K} acceptance criteria
→ Proceed? (yes / no / revise)
```
---
#### Phase 3 — Implement
Write code following these rules:
##### Design Discipline
- Component interfaces, method signatures, and return types MUST match the
design document exactly.
- Data model fields, types, and relationships MUST match the data design.
- API endpoints, request/response schemas, and status codes MUST match the
interface design.
- If a design decision proves impossible in practice, stop and report the gap
to the Builder. Do NOT silently deviate.
##### Code Quality
- Follow existing project conventions (read neighbor files first to
understand patterns).
- Use existing libraries and utilities already in the codebase — do not
introduce new dependencies without explicit justification.
- Keep functions small and single-purpose — but per `rules/style-guide`, do NOT
preemptively extract single-use helpers; inline at the call site unless the
helper is reused, hides a genuinely complex boundary, or has a clear
independent name that improves the caller.
- Handle errors at the appropriate layer (matching the design's error
handling strategy).
- Write self-documenting code; add comments only for genuinely non-obvious
logic.
- Document all new/modified public APIs inline (JSDoc/TSDoc/pydoc/etc.)
with parameter descriptions, return types, and thrown errors.
- If the project has an API documentation file (e.g. OpenAPI spec, API.md),
update it to reflect the new endpoints, schemas, or behavior changes.
##### Test Discipline
- **Test-first (Red → Green) for declared test_ids.** For every acceptance
criterion (node AC in `{epic-slug}/dag`, whose `test_id` mapping is declared
inline; historically the `04-plan-05-acceptance-criteria` table) that
declares a `test_id`, write that test FIRST and confirm it fails for the
intended reason (Red) before writing the implementation that satisfies it
(Green). The test's `file-path :: test-name` MUST match the declared
`test_id` exactly — this is the implement-side handshake with `verify`
(DOD-1.6). A `test_id` marked `MANUAL` or `BENCH:<script>` is implemented
per its method and is exempt from the Red step. If a test already passes
against existing code (the behavior is already present), note it in the
Phase 5 report rather than forcing an artificial failure.
- Write tests that verify the acceptance criteria.
- Tests must be independent (no shared mutable state).
- Test edge cases identified in the acceptance criteria.
- Test failure paths that the design specifies.
##### Incremental Commitments
- Implement in dependency order within the work item: shared types first,
then data access, then business logic, then API handlers.
- After each coherent unit, run typecheck to catch errors early.
---
#### Common Rationalizations
Implementation fails far more often from **pressure** than from ignorance — the
Developer knows the rules and rationalizes skipping them under context or time
pressure. These are the excuses that precede every review blocker and silent
defect. If you catch yourself thinking any row's "Excuse", stop: the "Reality"
column is the exact rule you are about to break, and breaking it is what turns
a one-pass implementation into a multi-round review.
| Excuse | Reality (the rule being broken) |
|--------|---------------------------------|
| "Design says X, but Y is simpler/better" | Silent deviation is a hidden design gap. Phase 3 Design Discipline: stop and report to the Builder — never silently deviate. |
| "Small change, a test is overkill" | A one-line edit can break a contract. Every acceptance criterion maps to ≥1 test (Phase 4 Brownfield check). 30 seconds now vs. a review blocker later. |
| "I'll write tests after it works" | Tests-after verify what you built, not what was required — you test your own bias, not the spec. |
| "Typecheck passed, lint is cosmetic" | Lint is a Phase 4 gate, not optional polish. Failing lint is an automatic review blocker. |
| "Self-check passed, I'll trust it" | Rubber-stamping misses the MAJORs the formal review will catch. Rule: if YOU can find a MAJOR, fix it now — the first review should never discover what you could have. |
| "This neighbor looks buggy, I'll fix it too" | Scope creep. Log it as an observation in the report; do not fix unrelated code (Greenfield/Brownfield rule). |
| "Spans 5 files but it's one logical change" | The ≤3-files rule is structural, not aesthetic. Split the work item via the Builder (Phase 2 rule). |
| "Design is ambiguous here, I'll pick the obvious option" | Inventing a design decision is a Phase 2 abort condition. Flag the gap; do not guess. |
| "Already manually verified it works" | Manual ≠ systematic — no record, can't re-run, can't bisect. `bun run test:changed` is the evidence the report demands. |
| "Report is busywork, the diff speaks for itself" | No report → review-code cannot trace AC→test. Phase 5 is the handoff contract; skip it and the review stalls. |
| "X× improvement — assumed, no measurement" | Quick-measure before it becomes an AC. Unverified assumptions in ACs waste framing cost ([org-internal #1932]: YAML token density assumed 2-3×, measured 0.95 — hypothesis rejected by data). |
---
#### Phase 4 — Self-Check
After writing all code, run the project's verification commands:
1. **Typecheck**: `bun typecheck` (or project-equivalent). Fix all type errors.
2. **Lint**: `bun oxlint --deny-warnings` (repo root — the review-code
mechanical gate's canonical lint invocation; `bun lint` is the package-script
alias). Fix all lint errors.
3. **Tests**: `bun run test:changed` (or project-equivalent). All affected tests must pass.
4. **Post-deletion cleanup** (mandatory when any code was removed): If files or code blocks were deleted (dead code, test cleanup, refactored-out modules), re-run `bun oxlint --deny-warnings` specifically to catch orphaned imports and unused variables — these are the most common post-deletion regressions. Re-run `bun typecheck` to catch orphaned type references to deleted modules.
Then self-check against `core/checklists/implementation.md`:
- Verify every checklist item marked PRE (pre-implementation) was satisfied
before coding.
- Verify every checklist item marked POST (post-implementation) is satisfied
now.
- For any failed checklist item, fix the code before reporting.
##### Brownfield Self-Check (additional)
For brownfield work items, additionally:
1. **Design spec cross-check**: Re-read the node's cross-session edge
contracts in the frozen DAG copy (historically the design's interface
design section, `03-design-04-interface-design`). Verify every interface
promise — method signatures, return types, output formats, error messages,
config field names, param descriptions — is satisfied exactly as specified.
Schema annotations MUST match actual code behavior.
2. **Test coverage**: For each new function, method, or exported API added,
confirm at least one test exercises it. If `bun run test:changed` reports zero new
tests, add them before handoff.
##### Review Readiness Self-Check (mandatory before handoff)
Before submitting to code review, the Developer MUST self-attest against the
code review checklist. This reduces round-trips by catching common defects
before the first review submission. **The self-check must achieve 0 BLOCKERs
and 0 MAJORs before handoff** — if the Developer can find a MAJOR issue during
self-check, the formal reviewers will find it too.
1. **Run the code review checklist**: Read `core/checklists/code-review.md`
and self-attest that the code likely passes, for each of its 10 dimensions
(COR, DGN, SEC, PERF, TST, STY, DBT, A11Y, DOC, TRC — the authoritative
dimension set lives in the checklist's section headers and
`review-code/reference/code-review-dimensions.md`; do NOT hand-maintain a
copy here).
2. Record the self-attestation in the Phase 5 report under "Review Readiness"
as a pass/fail per dimension. Any FAIL dimension MUST be fixed before handoff.
3. **Hard gate**: self-check MUST find 0 BLOCKERs and 0 MAJORs. If the
Developer finds even one MAJOR, fix it and re-run self-check before handoff.
The first formal code review should never discover issues the Developer
could have caught themselves.
---
#### Phase 4.5 — Iteration Completion Commit
After ALL work items in the current iteration have been implemented and passed
Self-Check (Phase 4), create a git commit BEFORE proceeding to the next
iteration. This preserves per-iteration traceability and enables `git bisect`
per iteration.
##### Commit Rules
1. Commit after the last WI of the iteration is done and self-checked.
2. Commit message format: `[{chunk-id}][{iteration}] {summary}`.
- Example: `[chunk-resolution][iter-1] feat: add two-pass chain resolution engine`
3. **Commit body is REQUIRED for non-trivial commits** (any commit touching > 1 file
or > 20 LOC). The body MUST contain:
- **What**: a 1-3 line summary of the changes (files + purpose), including
the work item ID (`WI-{NNN}`) the commit delivers — code-review TRC 10.1
requires the commit/PR description to carry the work item ID.
- **Why**: the design/requirement motivation (cite REQ-ID or ADR if applicable).
- **Evidence**: test names or verification commands run (e.g. `90 compaction
tests pass`).
- Subject-only commits are acceptable only for single-line fixes or doc tweaks.
4. Include all source + test files from the iteration.
5. After commit, proceed to Phase 4.6 (Issue Checklist Sync), then Phase 5
(Report) for the iteration, then start the next iteration's WIs.
##### Multi-Iteration Workflow
```
Iteration 1 WIs → Self-Check → Commit [iter-1] → Checklist Sync → Code Review →
Iteration 2 WIs → Self-Check → Commit [iter-2] → Checklist Sync → Code Review → Merge
```
---
#### Phase 4.6 — Issue Checklist Sync (progressive)
After committing the iteration, sync the source issue's checklist so
stakeholders see progress in real time. This is mandated by the
`issue-checklist-sync` L1 rule — follow its "How to sync (each point)"
procedure (identify source issue → fetch body → map → update, preserving
non-checklist content); this phase adds only the implement-specific annotation:
- **Stage-specific row**: for each `- [ ]` item the iteration's work satisfies,
mark `- [x]` and append `_(commit {sha}: file/component)_` or
`_(PR #NNN: file)_`.
- **Do NOT touch items outside this iteration's scope** — they will be caught
at a later sync point (next iteration, DAG-freeze aggregation sync, or
verify Phase 5.6). Only check off what this iteration actually delivered.
This is a **progressive** sync: the checklist fills in incrementally as
iterations complete, giving stakeholders a live view of progress without
waiting for the final verify gate.
#### Phase 4.7 — PR-Creation Sync
The session pushes its branch and reports `status=done branch=<ref> verify=…
risk=…`; the orchestrator admits the PR (serially, one open at a time) —
workers never open PRs (TD-678/[org-internal #4425]; `uncoordinated` self-open only when
the orchestrator is unreachable). Once that PR exists, update the source
issue so stakeholders see the mergeable state without waiting for code
review. Mandated by the `issue-checklist-sync` L1 rule; skip if no source
issue exists.
> PR shape per mode: default = one 1:1 PR per task (body carries the worker
> report); batch-mode epics ([org-internal #3731], per-epic opt-in) = the orchestrator
> composes ONE batch PR per iteration via the `land-batch` skill. This phase
> then runs per member issue as usual (N times), each pointing at its PR
> (batch: the single batch PR); the poller writes the PR/CI/review rows
> against every member issue (multi-close-ref fan-out).
1. Re-fetch the issue body via `工单 API（见 TERMINOLOGY）get`.
2. **Ensure the `## 当前状态` live-status section exists** (create it if
absent — MANDATORY for incident / standalone-bugfix flows; for quiet
pipeline flows, create it only if it already exists, otherwise skip). The
`PR` row itself is written by the `status-sync` poller
(`.gitea/scripts/status-sync-poll.ts`), NOT this skill — do NOT manually
`工单 API（见 TERMINOLOGY）update` the PR / 代码评审 / CI rows (per
`issue-checklist-sync.md` § Automated sync).
3. If this is an Epic task list, append the PR reference to the row that this
iteration's work corresponds to.
4. Preserve all non-checklist content.
5. **Never hand-sync main into the PR branch.** Keeping the PR mergeable is
the keep-mergeable workflow's job: once review converges the orchestrator
labels the PR `ready-to-merge` and the server-side keep-mergeable cron
(`.gitea/scripts/keep-mergeable.ts`, driven by
`script/keep-mergeable-cron.sh` under a systemd timer) fetches the PR head,
probes `merge-tree --write-tree`, and pushes a non-force `commit-tree` merge
into the head branch (the retired `POST /pulls/{n}/update-branch` API path
returned 405 on this instance — see AGENTS.md "PR keep-mergeable").
Hand-written `chore: merge origin/main (keep PR mergeable)` commits are
retired — each one re-triggered the full CI surface for near-zero re-tested
risk.
> **Kanban column lifecycle**: automated (`工单 API（见 TERMINOLOGY）create` → Backlog,
> `gitea_pull__create` → Review; no manual moves). Single shared reference:
> `_shared/gitea-write-patterns.md` Pattern 7.5; column semantics: wiki
> `kanban-lifecycle`.
---
#### Phase 5 — Report
Produce an implementation report:
```markdown
## Implementation Report: {WI-ID}
**Work item**: {description}
**Iteration**: {iteration number}: {goal}
### Files Changed
| File | Action | Purpose |
| ------------------ | -------- | -------------- |
| `path/to/file.ts` | created | {purpose} |
| `path/to/other.ts` | modified | {what changed} |
### Acceptance Criteria
| Criterion | Status | Evidence |
| ------------- | ------ | ---------------------------------- |
| {criterion 1} | ✅ | {test name or manual verification} |
| {criterion 2} | ✅ | {test name or manual verification} |
### Verification Results
- Typecheck: {pass / fail + error count}
- Lint: {pass / fail + warning count}
- Tests: {N} passed, {M} failed, {K} skipped
### Design Deviations
{list any intentional deviations from design with rationale, or "None"}
### Open Items
{anything incomplete with reason, or "None"}
---
**Handoff**: Ready for `core/skills/review-code/SKILL.md`
```
**Persist before returning ([org-internal #2847])**: the Developer MUST write the final
report above to disk as its LAST action, BEFORE returning it —
`<runs-root>/{slug}/workers/{chunk-id}-worker-{seq}.md` when the Tier 1
run workspace exists, else `/tmp/octopus/{chunk-id}-worker-{seq}.md`
(`{chunk-id}`/`{seq}` come from the dispatch prompt — see
`../_shared/worker-report-persistence.md`). The persisted copy is the
report of record; the task notification is a convenience copy. The same
step applies to EVERY mode's report phase (bugfix Phase 5, refactor
Phase 6, port report) — no worker return may exist only in the task
notification.
---
#### Phase 6 — Handoff to Code Review
Present the report to the user and signal readiness for review:
```
Implementation of {WI-ID} complete.
- {N} files changed ({C} created, {M} modified)
- {T} tests passing
- All acceptance criteria satisfied
- Typecheck + lint clean
→ Run code review? (yes / no)
```
Do NOT mark the work item as complete until code review passes.
To notify workflow completion, call the `signal_stage_done` tool.
#### Legacy notes
> **Publish target (tiered targeting retired, [org-internal #3072] phase 3)**: the
> `Size/*`-tiered publish rule (`rules/workflow-routing.md` §"Publish target
> by Size/* tier — RETIRED") was retired with the legacy producer skills.
> Artifacts publish where the live mode puts them: DAG task mode → node spec
> in the frozen `{epic-slug}/dag` copy (see the DAG-mode input path above);
> standalone bugfix → `{slug}/bugfix-report` + issue body per bugfix Phase 5.
> Legacy tiered locations (`{slug}/02-03-req-design`, `{slug}/04-plan-*`, …)
> stay readable for historical runs via `_shared/gitea-read-patterns.md`.
core/skills/implement/reference/large-port-pipeline.md
+252
View File
@@ -0,0 +1,252 @@
# Large Port Pipeline — Detailed Processes
> Extracted from `implement/SKILL.md` (Mode: port) Phase B1 through B4.
> Read this file when executing the Pipeline Mode for large ports.
---
## Phase B1 — Source Analysis
Produce a comprehensive source analysis under
wiki page namespace `port-{name}/source-analysis/`. This is the authoritative
behavioral contract that every downstream stage references.
### Directory Structure
```
port-{name}/source-analysis/
├── index # Summary & reading guide (wiki page)
├── 01-source-overview # Source project context, tech stack
├── 02-public-api.md # Every public endpoint / method / interface
├── 03-data-model.md # Entities, fields, relationships, schemas
├── 04-business-logic.md # Validation, rules, edge cases, state machines
├── 05-error-handling.md # Error types, codes, messages, recovery paths
├── 06-dependencies.md # Libraries, infrastructure, external services
├── 07-test-coverage.md # Test inventory: happy path, edge cases, errors
├── 08-concept-mapping.md # Source → target concept mapping (Phase A2)
├── 09-gap-analysis.md # Gaps, alternatives, decisions (Phase A3)
├── 10-fidelity-baseline.md # Full behavioral inventory for end-to-end verify
├── 11-target-surface.md # Target project receiving surface analysis (Phase B1.7)
└── 12-capability-boundary.md # Complete artifact inventory per capability (Phase B1.8)
```
### Document Templates
The format templates for documents 01–05 and 10 are in
`reference/source-analysis-templates.md` (read it when producing these
documents). Documents 06–09 follow the same table-based format as their
Phase A1/A2/A3 counterparts in standalone mode. The `10-fidelity-baseline.md`
document is the master inventory — every source behavior is listed as a
checkable `FID-*` item with a `Chunk` column that drives DAG node decomposition.
---
## Phase B1.5 — Source Analysis Review (GATE)
Before proceeding to self-check, ALL source analysis documents MUST pass
peer review. This is the single highest-leverage quality gate in the port
pipeline — errors in source analysis propagate to every downstream stage.
### Review Process
1. **Spawn 10 parallel reviewer sub-agents** (Explorer), one per dimension.
Each reviewer receives:
- The relevant source analysis documents (as listed per dimension below).
- The source project files (or accessible copies).
- The target project files (for TGT-SURF and CAP-BOUND dimensions).
- Review instructions for that dimension.
2. **Review dimensions**:
| Dimension | Documents Reviewed | Key Question |
| --------- | ------------------ | ------------ |
| SRC-CMP | 01-source-overview, 03-data-model, 04-business-logic, 10-fidelity-baseline | Is every source behavior/entity/rule captured? |
| SRC-API | 02-public-api, 05-error-handling | Is every public endpoint/method/error documented accurately? |
| SRC-DATA | 03-data-model | Are entities, fields, types, constraints, and relations correct? |
| SRC-BIZ | 04-business-logic | Are every validation rule, edge case, and state transition documented? |
| SRC-ERR | 05-error-handling | Are all error types, codes, messages, and recovery paths captured? |
| SRC-DEP | 06-dependencies | Are all libraries, infrastructure, and external services listed? |
| SRC-TST | 07-test-coverage, 10-fidelity-baseline | Does every source test case map to a FID item? Are file:line references correct? |
| SRC-MAP | 08-concept-mapping | Is every source concept mapped to a target equivalent or [GAP]? Are mappings correct? |
| TGT-SURF | 11-target-surface | Is the target project's receiving surface fully analyzed? Are all integration points, structural diffs, and readiness items captured? Does every source gap in the structural diff have a plan? |
| CAP-BOUND | 12-capability-boundary | Are all 13 artifact dimensions filled in? Does every Source Function Inventory item appear in D1/D2? Does every structural diff gap have a boundary entry? Are all N/A dimensions justified? |
3. **Output**: Each reviewer writes a findings JSON conforming to
`core/schemas/port-analysis.schema.json` as a
wiki page `port-{name}/source-analysis/reviews/{dimension}`
with format:
```json
{
"dimension": "SRC-CMP",
"findings": [
{
"id": "SRC-CMP-001",
"severity": "BLOCKER|MAJOR|MINOR",
"description": "...",
"source_evidence": "file:line",
"recommendation": "..."
}
]
}
```
4. **Synthesis**: An Orchestrator (Worker) collects all 10 dimension reports,
deduplicates, and produces a synthesis:
wiki page `port-{name}/source-analysis/reviews/synthesis`
with summary counts per dimension and consolidated action items.
5. **Iterate until convergence**:
- Developer addresses all BLOCKER and MAJOR findings.
- Reviewer re-checks affected dimensions.
- Repeat until all dimensions show 0 BLOCKER and 0 MAJOR.
6. **GATE**: Phase B2 cannot start until synthesis shows ALL dimensions
converged (0 BLOCKER, 0 MAJOR). Developer prints:
`SOURCE ANALYSIS REVIEW CONVERGED — 10/10 dimensions pass`
---
## Phase B1.7 + B1.8 — Target Surface & Capability Boundary (Pipeline)
In pipeline mode, Phase A1.7 (Target Surface Analysis) and Phase A1.8
(Capability Boundary Definition) produce formal artifacts in the
source-analysis directory for peer review:
- **`11-target-surface.md`** — same process and format as Phase A1.7, using
`reference/target-surface-template.md`. Reviewed by the **TGT-SURF**
dimension in Phase B1.5.
- **`12-capability-boundary.md`** — same process and format as Phase A1.8,
using `reference/capability-boundary-template.md`. Reviewed by the
**CAP-BOUND** dimension in Phase B1.5.
### Roadmap decomposition link
The capability boundary directly feeds the DAG decomposition (Phase B3):
- Chunks are defined by grouping capability boundary artifacts by source
module / feature area.
- Cross-chunk dependencies are derived from dimension 13 (shared package
changes).
- The fidelity baseline (`10-fidelity-baseline.md`) is partitioned across
chunks based on which capability boundary artifacts implement each FID item.
**GATE**: Do NOT proceed to Phase B2 until the B1.5 review converges on ALL
10 dimensions including TGT-SURF and CAP-BOUND.
---
## Phase B2 — Self-Check Source Analysis
Run the port checklist (`core/checklists/port.md`) against the source
analysis:
- Section 0.5 (SRV — Source Analysis Review): 10-dimension review converged.
- Section 0.7 (TGT — Target Surface Analysis): target receiving surface
fully mapped, structural diff complete, integration points identified.
- Section 0.8 (CAP — Capability Boundary): all 13 artifact dimensions filled,
cross-checks passed.
- Section 1 (SRC — Source Understanding): every source file and test read.
- Section 2 (MAP — Concept Mapping): every source concept has a target
equivalent or `[GAP]`.
- Section 3 (GAP — Gap Analysis): all gaps have alternatives and decisions.
- Sections 4–7 (ADAPT, FID, TST, BEH): deferred to downstream stages —
marked as `[DEFERRED TO DESIGN]`, `[DEFERRED TO IMPLEMENT]`, etc.
---
## Phase B3 — Handoff to DAG Decomposition
> Legacy note ([org-internal #3072] phase 3, 2026-08-21): this handoff used to target the
> archived `roadmap` skill; it now targets `analyze-dag`.
Present the source analysis and request task-DAG decomposition:
```
Source analysis complete for port-{name}.
- {N} source files ({L} LOC) across {M} modules
- {K} public API endpoints / methods documented
- {B} business rules captured
- {F} fidelity baseline items (for end-to-end verify)
- {G} gaps identified with alternatives
Artifacts: wiki pages under `port-{name}/source-analysis/`
→ Approve and begin DAG decomposition? (yes / no / revise)
```
Upon approval, the Builder routes to
`core/skills/analyze-dag/SKILL.md` with:
- **Slug**: `port-{name}`
- **Scope**: the source modules and fidelity baseline from the source analysis.
analyze-dag decomposes the port into a task DAG by source module / feature
area. Each node is a self-contained porting unit (e.g. `N-auth`, `N-api`,
`N-models`); node ACs derive from the source analysis (`FID-*` items become
ACs tracing to source tests; concept-mapping and gap decisions become the
node spec; porting order follows source-file dependency order as edge
topology). After the `review-dag` single gate PASSes, each node ticket flows
`dag.task_route`:
```
core/skills/implement/SKILL.md
→ core/skills/review-code/SKILL.md
→ core/skills/verify/SKILL.md
```
(The legacy per-chunk `requirements-elicitation` → `design` →
`review-artifact(design-space)` → `plan-iterations` → `review-artifact(plan)`
front-end was archived 2026-08-21, [org-internal #3072] phase 3 — `<instance-root>/archive/`.)
### implement
The Developer ports code following the rules from Phase A5 (target
conventions, fidelity over aesthetics, no new dependencies, port comments).
Additionally:
- Each implementation report references the corresponding `FID-*` items
from the fidelity baseline.
- Ported tests reference source test file and line number.
### review-code
Standard code review. Additionally:
- Reviewer checks fidelity: does the ported code match the source behavior
as documented in the chunk's requirements?
- Reviewer checks convention compliance: does the new code look native to
the target project?
### Target-Side Refactoring in Port Pipeline
Large ports often require restructuring the target codebase to accommodate
ported code — extracting interfaces, renaming conflicting modules, removing
dead code, or adapting existing abstractions. These refactoring needs MUST
flow through the pipeline's quality gates, not as ad hoc changes.
**Identification**: The Architect identifies target-side refactoring needs
during design and documents them as design decisions. Each refactoring
decision references the gap that requires it (e.g. "Target's UserService must
be extracted to an interface before porting source AuthService to avoid
tight coupling").
**Planning**: The Planner creates refactoring work items alongside
implementation work items. A refactoring work item's description starts with
"Refactor" (or 重构) and its requirements coverage maps to a refactoring
requirement derived from the design decision. Dependencies are enforced:
- Refactoring work items that unblock port work items appear earlier in the
iteration order.
- No port work item depends on an incomplete refactoring.
**Execution**: The `implement` skill handles refactoring work items via its
Refactoring Mode (see
`core/skills/implement/SKILL.md` — Refactoring Mode). The refactoring
produces a standard implementation report and proceeds to code review.
**Quality**: Refactoring work items go through the full review gate —
code review is mandatory regardless of change size. The reviewer verifies:
- Behavioral fidelity: did the refactoring preserve existing behavior?
- Test baseline: did any existing tests break or change?
- Design alignment: does the refactoring match the design decision?
```
pipeline for refactoring work items (DAG node):
implement (refactoring mode) → review-code → verify
```
core/skills/implement/reference/mapping-and-design.md
+102
View File
@@ -0,0 +1,102 @@
# Concept Mapping, Gap Analysis & Adaptation Design — Detailed Processes
> Extracted from `implement/SKILL.md` (Mode: port) Phase A2, A3, A4.
> Read this file when executing the Mapping and Design phases in standalone mode.
---
## Phase A2 — Map Concepts
For every source concept, identify the target project's equivalent. This is a
bidirectional mapping — every source entity, every source API call, every
source pattern must have a corresponding target concept.
### Mapping Table
| Source Concept | Target Equivalent | Notes |
| ------------------ | ------------------------------------------- | ---------------------------------------------------- |
| Express middleware | Fastify hook | Different signature — adapt order and error handling |
| Sequelize model | Drizzle schema | Different migration strategy — adapt CLI |
| bcrypt hash | argon2 | Target project's existing auth module uses argon2 |
| Redis cache | Memory cache (no Redis) | Compromise — simplify to in-memory with TTL |
| Pino logger | Existing logger module in `src/util/log.ts` | Reuse target's logger |
### Rules
- If a source concept has no clear target equivalent, pause and log `[GAP]`.
- If the target has a different pattern for the same concept (e.g. callbacks
vs. async/await), prefer the TARGET pattern, not the source's.
- If the source uses a library that exists in the target's ecosystem, use the
version already in the target's `package.json` — do not introduce a different
version.
---
## Phase A3 — Gap Analysis
For every `[GAP]` from Phase A2, analyze the impact:
### Gap Analysis Table
| Gap | Impact | Alternatives | Decision | Deferred To (slug) | Reactivation Trigger |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------- | ---------- | ------------------ | -------------------- |
| No Redis in target | Source uses Redis for session store | 1. Add Redis to target, 2. Use DB for sessions, 3. Use in-memory (not for production) | {decision} | | |
| No message queue | Source uses RabbitMQ for async tasks | 1. Add queue to target, 2. Make synchronous, 3. Use a simpler queue (e.g. database polling) | {decision} | | |
### Rules
- Do NOT add infrastructure to the target unless absolutely necessary — prefer
alternatives that use existing target infrastructure.
- If a gap forces a behavior change, mark it as `[FIDELITY DEVIATION]` — the
port will not behave identically. This must be explicitly approved.
### Deferral Rules
- A gap marked `Deferred` MUST populate both "Deferred To" and "Reactivation Trigger" columns.
- "Deferred To" must reference a concrete artifact slug (e.g. `port-{name}/chunk-http`).
- "Reactivation Trigger" must specify a condition (e.g. "After chunk-auth verification passes").
- Gaps without a reactivation path are treated as `[PORT GAP]` — a blocker for the current port.
---
## Phase A4 — Adaptation Design
Design how the source feature will fit into the target project:
1. **File structure** — where in the target project will the ported code live?
2. **Interface adaptations** — source API signatures must adapt to target
conventions (e.g. source uses `snake_case`, target uses `camelCase`).
3. **Dependency replacements** — for each source dependency, use the target
equivalent or the Gap decision from Phase A3.
4. **Test adaptation** — source test framework → target test framework mapping
(e.g. `describe`/`it` → `describe`/`it` if both use the same pattern, or
map to target's test DSL).
### Adaptation Design Template
````markdown
## Adaptation Design
### File Structure
```
src/
{module}/
{ported_file}.ts — (from source/src/{module}/{file}.js)
...
test/
{module}/
{ported_test}.test.ts — (from source/test/{module}/{file}.test.js)
```
### Interface Adaptations
| Source | Target | Reason |
|--------|--------|--------|
| `req.body.created_at` | `req.body.createdAt` | Target convention: camelCase |
| `throw new AppError(400, '...')` | `yield* new BadRequest('...')` | Target uses Effect errors |
### Fidelity Deviations
| What Changes | Why | Impact |
|-------------|-----|--------|
| Session store: Redis → DB | Target has no Redis | Slightly higher latency (~5ms), CAP consistency trade |
| Async queue: RabbitMQ → DB polling | Target has no queue broker | Higher latency, lower throughput — acceptable for < 100 ops/min |
````
core/skills/implement/reference/port-mode.md
+389
View File
@@ -0,0 +1,389 @@
> Extracted from implement/SKILL.md (Mode: port) — moved verbatim 2026-08-25, ticket [org-internal #3381].
### Mode: port
Port a feature from a source project into the current (target) project. Unlike
greenfield (no existing code), brownfield (new feature in same project), or
bugfix (restore intended behavior), porting requires preserving the source's
behavioral contract while adapting every implementation detail to the target's
tech stack and conventions.
#### Role & Responsibilities
The port is owned by the **Developer** (Worker).
The Developer is responsible for:
- Reading and understanding the source feature end-to-end.
- Mapping source concepts to target equivalents.
- Identifying gaps (missing infrastructure, incompatible libraries).
- Designing adaptations that preserve behavior.
- For small ports: implementing in the target project following target
conventions end-to-end.
- For large ports: producing a source analysis report, then handing off to
the DAG pipeline (analyze-dag → review-dag → per-node implement →
review-code → verify) with the single-gate review.
- Porting source tests to the target test framework.
- Verifying behavioral fidelity (same inputs → same outputs).
The Builder's role is to validate the port output and route to the next stage
(analyze-dag for large ports, code review for non-trivial small ports).
#### Tester focus for port
The Tester role in port writes **behavioral-fidelity tests** — verifying
that ported code behaves identically to the source, not just that it passes
its own assertions:
- **Fidelity-anchored tests** — every `FID-*` item in
`port-{name}/source-analysis/10-fidelity-baseline` (or `port-{name}/source-analysis/fid-raw` in standalone mode) MUST map
to at least one ported test. The Tester reads the source test for each
FID and rewrites it in the target test framework's assertion style,
preserving the behavioral contract (same inputs → same outputs).
- **Source-test porting** — port edge cases, error paths, and boundary
tests from the source, not just the happy path. Missing FID coverage is
the #1 cause of incomplete porting.
- **Fidelity-deviation tests** — for every `[FIDELITY DEVIATION]` in the
adaptation design (Phase A4), write a test that documents and locks the
divergent behavior so the deviation is intentional, not accidental drift.
The port orchestration follows the standard role-split flow (implement
before test): the Developer ports code in Phase A5 and runs test:changed
to green; the Tester then ports source tests and verifies fidelity in
Phase A6. In pipeline mode (Part 2), the role split applies within each
chunk's implement stage.
---
#### Phase 0 — Scope Assessment
Before starting, measure the source scope across **four dimensions** — file
count and LOC alone are insufficient because a 3-file port that spans 3
packages with implicit dependencies (schema, config, routes) is far more
complex than a 10-file port within a single self-contained module.
1. Count source files in the feature scope.
2. Count total source lines of code (exclude tests).
3. Count source modules / feature areas (distinct functional areas).
4. **Count source packages touched** — how many monorepo packages does the
feature span? (e.g. `packages/app`, `packages/sdk`, `packages/ui`,
`packages/core`).
5. **Count implicit dependency artifacts** — schema/migration files, config
entries, env vars, CLI flags, theme/style files, route definitions,
Provider/context hierarchy changes, build config changes. These are the
artifacts that are NOT source code files but are required for the feature
to function. See Phase A1.8 for the full artifact dimension list.
Determine the port path:
| Scope | Mode | Pipeline |
| ---------------------------------- | ------------- | ------------------------------------------------------ |
| ≤ 5 files, ≤ 200 LOC, 1 package, 0 implicit deps | **Standalone**| Standalone Developer flow (Phases A1–A8, mandatory code review) |
| > 5 files or > 200 LOC | **Pipeline** | Full pipeline: source analysis → analyze-dag → per-node |
| Spans ≥ 3 source modules | **Pipeline** | Full pipeline (regardless of file count / LOC) |
| Spans ≥ 2 packages | **Pipeline** | Full pipeline (cross-package ports have hidden coupling) |
| ≥ 3 implicit dependency artifacts | **Pipeline** | Full pipeline (implicit deps require capability boundary analysis) |
Report the assessment:
```
Port scope assessment:
- Source files: {N}
- Source LOC: {L}
- Source modules: {M}
- Source packages touched: {P}
- Implicit dependency artifacts: {I}
- Path: A (standalone) / B (full pipeline)
→ Proceed? (yes / no / revise)
```
Do NOT proceed without explicit approval.
---
#### Preconditions
- [ ] Source project path or reference is specified.
- [ ] Source feature scope is specified (which files, module, or feature).
- [ ] Target project is the current working directory and has a clean
workspace.
- [ ] Target project has an existing test framework.
- [ ] **Target project structure is accessible** — the Developer can read all
target project packages, config files, and build configs. If the target
is a monorepo, all packages must be accessible.
- [ ] **Target project's existing capabilities are documented or discoverable**
— the Developer must be able to identify what the target already has
(existing modules, routes, providers, schemas) to avoid redundant porting
and to identify integration points. If not documented, the Developer
must run a structural survey (Phase A1.7) before proceeding.
- [ ] `core/checklists/port.md` is accessible.
If the target project has no test framework, warn:
```
Target project has no test framework. Porting without tests cannot verify
behavioral fidelity. Options:
1. Add a test framework to the target project first.
2. Proceed without tests — behavioral fidelity cannot be guaranteed.
```
---
#### Part 1 — Standalone Mode (Small Port)
For small ports (≤ 5 files, ≤ 200 LOC), the Developer executes the full
port lifecycle directly. No DAG decomposition, no per-stage review gates.
Code review is mandatory (regardless of size, per Phase A8).
| Phase | Summary | Detail |
|-------|---------|--------|
| A1 | Deeply analyze source: public API, data model, dependencies, function inventory, test-to-FID extraction | `reference/source-analysis.md` |
| A1.5 | Source Analysis Review GATE — 4-dimensional peer review of A1 deliverables | `reference/source-analysis.md` |
| A1.7 | Target Surface Analysis — map target receiving surface, structural diffs, integration points | `reference/source-analysis.md` |
| A1.8 | Capability Boundary Definition GATE — 13-dimension artifact inventory | `reference/source-analysis.md` |
| A2 | Map every source concept to a target equivalent or mark as `[GAP]` | `reference/mapping-and-design.md` |
| A3 | Gap Analysis — alternatives, decisions, deferral paths for every `[GAP]` | `reference/mapping-and-design.md` |
| A4 | Adaptation Design — file structure, interface adaptations, fidelity deviations | `reference/mapping-and-design.md` |
| A5 | **Implement** — port code following target conventions | *(inline below)* |
| A5.5 | **Self-Check Gate** — complete port checklist | *(inline below)* |
| A6 | Port Tests & Verify Fidelity — port every test, fidelity checklist | `reference/fidelity-verification.md` |
| A7 | **Report** — produce port report | `reference/port-report-template.md` |
| A8 | **Approval** — present report, route to code review | *(inline below)* |
##### Phase A1 — Understand Source
Deeply analyze the source feature: public API, data model, dependencies, and
function inventory. Extract every test case as a `FID-*` entry in `port-{name}/source-analysis/fid-raw` (wiki page).
See `reference/source-analysis.md` for the full process, templates, and
Function Inventory format.
##### Phase A1.5 — Source Analysis Review (GATE)
A reviewer (Explorer sub-agent) cross-checks all A1 deliverables against source
files across 4 dimensions (SRC-CMP, SRC-API, SRC-TST, SRC-DEP). All BLOCKER
findings must be resolved before Phase A2. See `reference/source-analysis.md`.
##### Phase A1.7 — Target Surface Analysis
Analyze the target project's receiving surface: directory tree, existing
capabilities, automated structural diffs, integration points, and readiness.
See `reference/source-analysis.md` for the full process.
Output follows `reference/target-surface-template.md`.
##### Phase A1.8 — Capability Boundary Definition (GATE)
Define the complete artifact boundary across all 13 dimensions (code, types,
schema, config, env, CLI, theme, routes, providers, build, deps, tests, shared
packages). Cross-reference with A1 inventory and A1.7 diffs.
See `reference/source-analysis.md` for the full process.
Output follows `reference/capability-boundary-template.md`.
##### Phase A2 — Map Concepts
Map every source concept to a target equivalent — bidirectional, complete.
Mark missing equivalents as `[GAP]`. See `reference/mapping-and-design.md`.
##### Phase A3 — Gap Analysis
Analyze every `[GAP]`: impact, alternatives, decision, deferral path with
reactivation trigger. See `reference/mapping-and-design.md`.
##### Phase A4 — Adaptation Design
Design file structure, interface adaptations, dependency replacements, and
document `[FIDELITY DEVIATION]` items. See `reference/mapping-and-design.md`.
##### Phase A5 — Implement
Port the code file by file, following these rules:
1. **One file at a time** — port completely, verify, then move to the next.
2. **Target conventions are law** — the ported code must follow target
conventions exactly. Use target's naming, patterns, and idioms.
3. **Fidelity over aesthetics** — do not "improve" the source logic. If the
source validates email with `/^.+@.+$/`, port that exact validation (then
log a `[NOTE: weak validation in source]`). If you want stricter validation,
that's a separate feature item, not part of the port.
4. **Port comments from source** (translated to target language) — they capture
the original author's intent.
5. **After each file** — run `bun typecheck` to catch type errors early.
6. **Do not introduce new dependencies** — if the source uses a library not in
the target's lockfile, use the alternative from the adaptation design or
reimplement the needed subset inline.
##### Phase A5.5 — Self-Check Gate (MANDATORY)
Before proceeding to test porting, the Developer MUST complete the port
checklist (`core/checklists/port.md`) in full:
1. **Run every checklist section** — all 12 sections, all items.
2. **Mark every item** — ☑ (pass) or ☐ (fail) with written justification.
3. **For any ☐ item** — document a fix plan inline in the remarks column.
If the item is a known deferral (e.g. infrastructure gap), the deferral
must include a reactivation path (chunk + trigger).
4. **Publish the completed checklist** as a Gitea wiki page:
`wiki 读写 API（见 TERMINOLOGY）(owner="Octopus", repo="octopus", title="port-{name}/self-check", content="{checklist body}", message="Publish port self-check for {name}")`.
5. **GATE** — do NOT proceed to Phase A6 until:
- All items are ☑, OR
- All ☐ items have documented fix plans with reactivation paths,
AND the Developer has printed: `SELF-CHECK COMPLETE — {X} items passing, {Y} items deferred with plan`
##### Phase A6 — Port Tests & Verify Fidelity
Port every source test to the target test framework. Run all tests (ported +
existing), verify behavioral fidelity, and produce a fidelity verification
table. See `reference/fidelity-verification.md` for the full process and
fidelity checklist template.
##### Phase A7 — Report
Produce a port report following the template in
`reference/port-report-template.md`. The report covers: fidelity assessment
(fully ported / adapted / deferred / N/A), portfolio map (source → target file
mapping), gaps & deferred items, and verification results.
##### Phase A8 — Approval
Present the report:
```
Port complete: {one-line summary}
- {N} files ported ({L} lines)
- {M} tests ported, all pass
- Fidelity: {X}% fully ported, {Y}% adapted, {Z}% deferred
→ Run code review? (mandatory)
```
---
#### Part 2 — Pipeline Mode (Large Port)
For large ports, the Developer produces a source analysis report as the
foundation artifact, then the port flows through the full pipeline with
peer-review gates at every stage:
```
port (source analysis)
→ analyze-dag (decompose by source module into DAG nodes)
→ review-dag single gate (replaces the legacy design-space + plan reviews)
→ per node (dag.task_route):
implement (port code, target conventions) — see ### Mode: implement (default)
→ review-code
→ verify (integration + fidelity)
```
> Legacy diagram (archived [org-internal #3072] phase 3): the former per-chunk pipeline ran
> requirements-elicitation → design → review (target: design-space) →
> plan-iterations → review (target: plan) → implement → review-code. Those
> skills/targets are archived (`<instance-root>/archive/`); the live path is the
> analyze-dag → review-dag route above (see Phase B3/B4 below).
| Phase | Summary | Detail |
|-------|---------|--------|
| B1 | Produce comprehensive 12-document source analysis | `reference/large-port-pipeline.md` |
| B1.5 | **GATE** — 10-dimensional peer review of source analysis | `reference/large-port-pipeline.md` |
| B1.7+B1.8 | Target surface & capability boundary as formal artifacts for peer review | `reference/large-port-pipeline.md` |
| B2 | Self-check source analysis against port checklist | `reference/large-port-pipeline.md` |
| B3 | Handoff to analyze-dag — decompose by source module into DAG nodes (legacy: roadmap skill, archived [org-internal #3072] phase 3) | `reference/large-port-pipeline.md` |
| B4 | Per-node DAG task route: implement → review-code (the review-dag single gate replaces the legacy design-space + plan reviews at the Epic level) | `reference/large-port-pipeline.md` |
| B5 | Verify — integration + fidelity, every `FID-*` traced to a passing test | `reference/fidelity-verification.md` |
| B6 | **Final Approval** — consolidated port report | *(inline below)* |
##### Phase B1 — Source Analysis
Produce a comprehensive 12-document source analysis as Gitea wiki pages under
`port-{name}/source-analysis/`. Each document is a separate wiki page.
See `reference/large-port-pipeline.md` for the full document list, templates (in
`reference/source-analysis-templates.md`), and production process.
##### Phase B1.5 — Source Analysis Review (GATE)
Spawn 10 parallel Explorer reviewers across all dimensions (SRC-CMP, SRC-API,
SRC-DATA, SRC-BIZ, SRC-ERR, SRC-DEP, SRC-TST, SRC-MAP, TGT-SURF, CAP-BOUND),
synthesize findings, and iterate until convergence (0 BLOCKER, 0 MAJOR).
See `reference/large-port-pipeline.md` for the full process.
##### Phase B1.7 + B1.8 — Target Surface & Capability Boundary
Same processes as A1.7/A1.8, producing formal artifacts (`11-target-surface.md`,
`port-{name}/source-analysis/12-capability-boundary`) for peer review. The capability boundary feeds
directly into DAG node decomposition.
See `reference/large-port-pipeline.md`.
##### Phase B2 — Self-Check Source Analysis
Run the port checklist against the source analysis (sections 0.5, 0.7, 0.8, 1,
2, 3; sections 4–7 deferred to downstream stages).
See `reference/large-port-pipeline.md`.
##### Phase B3 — Handoff to DAG Decomposition
Present source analysis summary and request task-DAG decomposition. The
Builder routes to `core/skills/analyze-dag/SKILL.md` with slug
`port-{name}` (nodes per source module; the source analysis supplies node
ACs and edge contracts). (Legacy: this handed off to the archived `roadmap`
skill — `<instance-root>/archive/skills/roadmap/`, [org-internal #3072] phase 3.) See
`reference/large-port-pipeline.md` for the handoff format.
##### Phase B4 — Per-Node Pipeline
Each node ticket flows `dag.task_route`: `implement` → `review-code`
(the `review-dag` single gate replaces the legacy design-space + plan
reviews at the Epic level). Includes rules for target-side refactoring work
items routed through the refactor workflow (see Mode: refactor above).
See `reference/large-port-pipeline.md` for full per-stage details.
##### Phase B5 — Verify (Integration + Fidelity)
Run `core/skills/verify/SKILL.md` with the fidelity baseline as acceptance
criteria. Every `FID-*` must trace to a passing test. Produce a consolidated
Port Fidelity Report. See `reference/fidelity-verification.md`.
##### Phase B6 — Final Approval
Before declaring the port complete, verify:
1. **CI is configured** — Check `.gitea/workflows/` (this repo's CI location),
`.github/workflows/ci.yml`, or equivalent.
If absent, warn: `[GAP: no CI — no automated gate before merge]`.
The PR may be merged, but flag the gap in the port report.
2. **All review gates passed** — The `review-dag` single gate and every
node's code review have `converged: true`.
3. **Final typecheck + lint + tests pass** — Run all three commands fresh.
Present the consolidated port report:
```
Port complete: port-{name}
- {N} chunks implemented
- {F} files ported ({L} lines)
- {T} tests ported, all pass
- Fidelity: {X}/{Y} behaviors verified, {Z} deferred
- All peer-review gates passed
- CI: {configured / absent — manual gate required}
Artifacts: wiki pages under `port-{name}/`
→ Approve port? (yes / no)
```
##### Phase B7 — Post-Merge Cleanup
After the PR is merged and the port branch is no longer needed:
1. **Delete the remote branch**:
```
git push origin --delete workflow/port/{name}
```
2. **Delete the local branch**:
```
git branch -d workflow/port/{name}
```
3. **Remove associated worktrees**:
```
git worktree list | grep "workflow/port/{name}" | awk '{print $1}' | xargs git worktree remove
```
4. **Verify cleanup**: `git branch -a | grep workflow/port/{name}` should
return empty.
core/skills/implement/reference/port-report-template.md
+43
View File
@@ -0,0 +1,43 @@
# Port Report Template
```markdown
# Port Report
**Source**: {project name} — {feature name}
**Target**: {current project}
**Files ported**: {N}
**Tests ported**: {M}
## Fidelity Assessment
| Category | Status | Count |
| ------------------------------------- | ------ | ------------- |
| Fully ported | ✅ | {N} behaviors |
| Adapted (minor change) | ⚠️ | {N} behaviors |
| Deferred (not ported) | ❌ | {N} behaviors |
| Not applicable (different tech stack) | N/A | {N} behaviors |
## Portfolio Map
| Source File | Target File | Lines | Status |
| -------------------------------- | -------------------------------- | --------- | ------ |
| `source/src/auth/login.js` | `target/src/auth/login.ts` | 45 → 52 | ✅ |
| `source/test/auth/login.test.js` | `target/test/auth/login.test.ts` | 120 → 118 | ✅ |
## Gaps & Deferred
| Item | Reason | Deferred to |
| ------------- | -------------------------- | ------------------------------------- |
| Rate limiting | Target has no rate limiter | Separate feature: "Add rate limiting" |
## Verification
- Ported tests: {M} passed, 0 failed
- Existing tests: {K} passed, 0 failed
- Typecheck: ✅
- Lint: ✅
---
**Handoff**: → Run `core/skills/review-code/SKILL.md` (mandatory for all ports, regardless of size)
```
core/skills/implement/reference/refactor-mode.md
+258
View File
@@ -0,0 +1,258 @@
> Extracted from implement/SKILL.md (Mode: refactor) — moved verbatim 2026-08-25, ticket [org-internal #3381].
### Mode: refactor
Restructure existing code to improve maintainability, readability, or
performance without changing observable behavior. The existing test suite
is the safety net — every refactoring step MUST be verified before proceeding.
#### Execution Modes
| Mode | Entry Point | Scope Source | Review Gate |
| ---------- | -------------------------------------------- | --------------------------- | ---------------------- |
| Standalone | User says "refactor {X}" | User specifies scope | Optional (>50 lines or ≥5 files) |
| Pipeline | `implement` skill dispatches refactoring WI | Node spec (DAG) or request | Mandatory |
In pipeline mode, the scope and target pattern come from the design document
and iteration plan, not from user input. The Developer must read the design
sections referenced by the work item before starting Phase 1. After completing
Phases 1–6, the Developer produces the standard implementation report (see
Mode: implement (default), Phase 5) and hands off to code review.
#### Role & Responsibilities
The refactoring is owned and executed by the **Developer** (Worker). The
Developer owns both implementation and refactoring — same role, same skill set.
The Developer is responsible for:
- Establishing a passing test baseline before any code change.
- Decomposing the refactoring into small, reversible, verifiable steps.
- Running the full test suite after every step — never skip a verification.
- Reverting immediately if any step causes a test failure.
- Comparing before/after coverage and complexity metrics.
The Builder's role is to present the refactor report and route to code review
if the change is non-trivial (> 50 lines or touches ≥ 5 files).
---
#### Preconditions
Before starting the refactoring, confirm:
- [ ] Scope is specified (which file, module, or pattern to refactor).
- [ ] An existing test suite covers the scope. If test coverage is unknown,
run the test suite with coverage first.
- [ ] No uncommitted changes in the working tree (`git status` is clean).
- [ ] `core/checklists/refactoring.md` is accessible.
##### No Test Coverage? Stop.
If the scope has **no existing tests**:
```
Cannot safely refactor {scope} — no existing test coverage.
Refactoring without tests is not restructuring, it's rewriting with unknown
side effects. Options:
1. Write characterization tests first (tests that capture current behavior),
then refactor.
2. Skip this module — refactor only modules with test coverage.
```
---
#### Phase 1 — Scope & Baseline
1. **Identify scope** — confirm the exact files, classes, or modules to
refactor. Use `glob` and `grep` to map all files and their dependents.
2. **Establish baseline**:
- Run `bun run test:parallel` (or project-equivalent) — all tests must pass.
- If any test fails before you start, stop and report: "Cannot begin
refactoring with failing tests. Fix them first."
- Capture test count as baseline: `tests: {N} total, {N} passed`.
- Capture coverage if available: run the package's coverage script from
the package dir (e.g. `cd <harness-package> && bun run test:coverage`) —
`bun run test:parallel` does not emit coverage (its runner script drops
positional args, so `test:parallel --coverage` silently ignores the
flag); use the package's `test:coverage` script instead.
3. **Capture complexity metrics** (optional but recommended):
- Lines of code in scope.
- Cyclomatic complexity or equivalent (if tooling exists).
- Dependencies (fan-in / fan-out).
```markdown
## Baseline
**Scope**: {list of files}
**Tests**: {N} passed, 0 failed
**Coverage**: {X}% lines, {Y}% branches
**LOC**: {N}
**Complexity**: {measured or "no metrics tool available"}
```
---
#### Phase 2 — Define Target Pattern
Define what "done" looks like. A refactoring without a target pattern is
code churn, not improvement.
The target pattern must be one of:
| Category | Examples |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| **Extract** | Extract class, extract function, extract module |
| **Inline** | Inline function, inline variable, inline class |
| **Rename** | Rename function, variable, class, file, module |
| **Move** | Move function/class to a more appropriate module |
| **Replace** | Replace callback with Promise/await, replace loop with functional style, replace conditional with polymorphism |
| **Simplify** | Remove dead code, collapse redundant logic, flatten nested conditionals |
| **Upgrade** | Migrate to new API, adopt new library version patterns |
```markdown
## Target Pattern
**Category**: {Extract | Inline | Rename | Move | Replace | Simplify | Upgrade}
**Goal**: {one sentence — e.g. "Extract UserRepository from UserController to
separate persistence logic from HTTP handling"}
**Success criteria**:
1. All existing tests pass unchanged.
2. {specific structural goal — e.g. "UserController no longer imports Database"}.
3. Coverage does not decrease.
4. {additional criteria if applicable}.
```
---
#### Phase 3 — Decompose into Steps
Break the refactoring into the smallest individually-verifiable steps.
Each step must:
- Be reversible (if tests break, revert and reassess).
- Pass the full test suite independently.
- Be one conceptual transformation (not "rename + extract + inline" in one step).
- Take ≤ 5 minutes to write.
```markdown
## Refactoring Steps
| Step | Action | Files Affected | Expected Outcome |
| ---- | ----------------------------------------------- | ------------------------------------------------ | ---------------------------------- |
| 1 | Extract `findById` method from controller | `user.controller.ts`, `user.repository.ts` (new) | Controller delegates to repository |
| 2 | Extract `create` method | `user.controller.ts`, `user.repository.ts` | Same pattern as step 1 |
| 3 | Inline `formatUser` helper (used once) | `user.controller.ts` | Remove one-line helper |
| 4 | Rename `user.controller.ts` → `user.handler.ts` | `user.controller.ts`, 3 imports | Naming consistency |
```
**Rules**:
- Present the step plan to the user before executing.
- If > 10 steps, the scope is too large — split into multiple refactoring
sessions.
- The user may approve, reorder, or reject individual steps.
---
#### Phase 4 — Incremental Execution
For each step, in order:
1. **Transform**: apply the single conceptual change.
2. **Verify**: run `bun run test:changed` — ALL affected tests must pass.
3. **If PASS**: commit the step with a message describing the transformation:
```
refactor: extract {what} from {where}
```
4. **If FAIL**: revert the change. Do NOT fix the test or the code. Assess
whether the step decomposition is wrong or the test was already flaky.
- If the test was flaky (fails non-deterministically), fix the test first
as a prerequisite step, then retry.
- If the step decomposition is wrong, re-decompose from Phase 3.
**Revert policy**: revert immediately on failure. Do not attempt to fix
within the same step — a failing test during refactoring means the step is
not behavior-preserving, and you must find a smaller decomposition.
---
#### Phase 5 — Final Validation
After all steps are complete:
1. **Full test suite**: `bun run test:parallel` — all tests must pass.
2. **Typecheck**: `bun typecheck` — zero errors.
3. **Lint**: `bun oxlint --deny-warnings` — zero errors.
4. **Coverage comparison**: compare post-refactor coverage to baseline.
Coverage MUST NOT decrease (within ±1% for measurement noise).
5. **Complexity comparison** (optional): confirm the refactoring improved
the target metric (e.g. lower cyclomatic complexity).
---
#### Phase 6 — Report
```markdown
# Refactor Report
**Scope**: {module/pattern}
**Target**: {one-sentence goal}
**Steps executed**: {N}
## Before / After
| Metric | Before | After | Delta |
| ---------------- | ------ | ----- | --------- |
| LOC in scope | {N} | {N} | {N} |
| Coverage (lines) | {X}% | {Y}% | {delta} |
| Complexity | {N} | {N} | {delta} |
| Files touched | — | {N} | — |
| Tests | {N} | {N} | 0 changed |
## Steps
| # | Action | Outcome |
| --- | ------------------ | ------------- |
| 1 | Extract `findById` | ✅ tests pass |
| 2 | Extract `create` | ✅ tests pass |
| ... | ... | ... |
## Verification
- `bun run test:parallel`: {N} passed, 0 failed
- `bun typecheck`: ✅
- `bun oxlint --deny-warnings`: ✅
- Coverage delta: {delta}
## Design Deviation
{If the refactoring changes the internal architecture in a way that merits an
ADR, reference the ADR. **Deprecated:** `.artifacts/{slug}/design/adr/{NNNN}-*.md`
→ ADRs now live on the Gitea wiki at page `{slug}/03-adr-{NNNN}-{title}`,
readable via `gitea_wiki__get_page`. Or "None".}
---
**Handoff**: {if > 50 lines or ≥ 5 files → run `core/skills/review-code/SKILL.md`
| otherwise → refactor complete, no review needed}
```
---
#### Phase 7 — Approval
Present the report:
```
Refactor complete: {one-line summary}
- {N} steps executed, all tests pass
- {before} → {after} ({delta} LOC)
- Coverage: {before}% → {after}%
→ {if review needed: "Run code review?" | else: "Refactor complete. Approve?"}
```
core/skills/implement/reference/source-analysis-templates.md
+105
View File
@@ -0,0 +1,105 @@
# Source Analysis — Document Templates
> Used by Phase B1 (pipeline mode).
> Read this file when producing the source-analysis document set.
> Each section below is the template for the corresponding numbered file
> under `port-{name}/source-analysis/` (wiki pages via `wiki 读写 API（见 TERMINOLOGY）`).
## 01-source-overview.md
```markdown
## Source Overview
- **Project**: {name}
- **Language / Runtime**: {e.g. Python 3.11}
- **Framework**: {e.g. FastAPI}
- **Feature scope**: {description of what's being ported}
- **Source files**: {N}
- **Source LOC**: {L}
- **Source modules**: {list of distinct functional areas}
```
## 02-public-api.md
Document every public interface:
```markdown
## Public API
| Method / Endpoint | Input Schema | Output Schema | Errors | Notes |
| ----------------- | -------------- | --------------- | --------------------- | --------------- |
| POST /auth/login | `{email, pw}` | `{token, user}` | 400, 401, 429, 500 | Rate limited |
| GET /users/:id | path param | `User` object | 401, 403, 404 | Auth required |
```
## 03-data-model.md
```markdown
## Data Model
### Entity: User
| Field | Type | Constraints |
| ----------- | ---------- | ------------------- |
| id | UUID | PK, not null |
| email | string | unique, not null |
| password | string | hashed, not null |
| created_at | datetime | not null |
### Relationships
- User 1—N Session
- User N—M Role
```
## 04-business-logic.md
Capture every business rule, validation, edge case, and state transition
from the source. Write each rule as an executable assertion:
```markdown
## Business Logic
### Login
- RULE-01: Valid credentials → return JWT + user object
- RULE-02: Invalid password → 401 "Invalid credentials"
- RULE-03: Non-existent email → 401 "Invalid credentials" (same message, no enumeration)
- RULE-04: 5 failed attempts in 1 min → 429 + lock for 15 min
- RULE-05: Locked account + valid password → 423 "Account locked"
### Edge Cases
- Empty email → 400 "Email is required"
- Email > 254 chars → 400 "Email too long"
- Password < 8 chars → 400 "Password too short"
```
## 05-error-handling.md
```markdown
## Error Handling
| Error Code | HTTP Status | Message | Source Condition |
| ---------- | ----------- | -------------------- | --------------------- |
| AUTH_001 | 400 | Email is required | empty email |
| AUTH_002 | 401 | Invalid credentials | wrong email or pw |
| AUTH_003 | 429 | Too many attempts | rate limit exceeded |
| AUTH_004 | 423 | Account locked | locked out |
```
## 10-fidelity-baseline.md
This is the master inventory used by `verify` at the end. Every source
behavior is listed as a checkable item:
```markdown
## Fidelity Baseline
| ID | Behavior | Type | Source Test | Chunk |
| ---------- | ----------------------------------- | ------------ | -------------------- | ------------ |
| FID-001 | Login with valid credentials | happy path | test_login_ok | chunk-auth |
| FID-002 | Login with invalid password | error path | test_login_bad_pw | chunk-auth |
| FID-003 | Login with empty email | edge case | test_login_empty | chunk-auth |
| FID-004 | Rate limiting after 5 attempts | error path | test_rate_limit | chunk-auth |
```
Each `FID-*` item maps to a `Chunk` column — this drives the DAG node
decomposition. Behaviors in the same chunk are ported together. The
`Source Test` column traces back to the original test for the verify stage.
core/skills/implement/reference/source-analysis.md
+301
View File
@@ -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.
core/skills/implement/reference/target-surface-template.md
+52
View File
@@ -0,0 +1,52 @@
# Target Surface Analysis — Output Template
> Used by Phase A1.7 (standalone) and Phase B1.7 (pipeline).
> Read this file when executing the Target Surface Analysis phase, then
> produce the output document following this format.
Publish the output to wiki page `port-{name}/source-analysis/target-surface`
(standalone) or `port-{name}/source-analysis/11-target-surface`
(pipeline) via `wiki 读写 API（见 TERMINOLOGY）`.
```markdown
## Target Surface Analysis
### Target Project Structure
- Package map (package name → role)
- Relevant directory trees
### Existing Capabilities (overlapping with source)
| Target Module | Overlap with Source | Action (reuse / replace / extend) |
| ------------- | ------------------- | --------------------------------- |
| ... | ... | ... |
### Structural Diff Summary
| Dimension | Source has | Target has | Gap |
| --------------- | ---------- | ---------- | --- |
| Files (.tsx) | {N} files | {M} files | {N-M} new |
| Dependencies | {list} | {list} | {diff} |
| Export symbols | {list} | {list} | {diff} |
| Routes | {list} | {list} | {diff} |
| Providers | {list} | {list} | {diff} |
| Schemas | {list} | {list} | {diff} |
| CLI commands | {list} | {list} | {diff} |
| Theme files | {list} | {list} | {diff} |
| Config entries | {list} | {list} | {diff} |
| Env vars | {list} | {list} | {diff} |
| Build config | {list} | {list} | {diff} |
### Integration Points
| Integration Point | Change Required | Affected Target Files |
| ----------------- | --------------- | --------------------- |
| Route table | Add /new-session route | src/app.tsx |
| Provider hierarchy | Insert TabsProvider | src/app.tsx |
| ... | ... | ... |
### Target Readiness
| Readiness Item | Required? | Complexity | Blocking? |
| -------------- | --------- | ---------- | --------- |
| New package | No | — | No |
| Interface extraction | Yes | Medium | Yes |
| Migration | Yes | Low | Yes |
| Config schema | No | — | No |
```
core/skills/implement/reference/work-item-detection.md
+123
View File
@@ -0,0 +1,123 @@
> Extracted from implement/SKILL.md (Pipeline Work Item Detection) — moved verbatim 2026-08-25, ticket [org-internal #3381].
## Pipeline Work Item Detection
Not all work items in an iteration plan involve writing new code. Some require
fixing bugs, restructuring existing code, porting features, or building
frontend UI. These specialized work items use different execution workflows
(defined above) but flow through the same pipeline gates (review-code →
verify; DAG-routed work resolves its spec from `{epic-slug}/dag`).
### Refactoring Work Items
A work item is a refactoring work item when:
- Its description starts with "Refactor", "重构", "Restructure", "Extract",
"Inline", "Move", "Rename", "Simplify", "Upgrade", or "Remove dead code".
- It is explicitly tagged `[REFACTOR]` in the node ticket / request.
- The node spec identifies it as a structural change that preserves
behavior (no new capabilities, no bug fixes).
- Requirements coverage is a refactoring requirement (REQ-REFACTOR-*).
When a work item is a refactoring work item, follow the workflow defined in
Mode: refactor above with these adaptations:
1. **Scope & Baseline** (refactor Phase 1): The scope is the node spec /
work-item description, not free-form user input.
2. **Define Target Pattern** (refactor Phase 2): The target pattern must align
with the baseline's architecture decisions (node spec + contracts). If the
baseline does not prescribe a pattern, justify the choice in the refactor
report.
3. **Decompose into Steps** (refactor Phase 3): Present steps to the user for
approval per the refactor workflow. If the design document decides the target
pattern, the steps are not negotiable — they are derived from that decision.
4. **Incremental Execution** (refactor Phase 4): Same as standalone refactor.
Commit each step separately.
5. **Final Validation** (refactor Phase 5): Run `bun run test:parallel`, `bun typecheck`,
`bun oxlint --deny-warnings`. Coverage must not decrease.
6. **Produce the implementation report** using the standard Phase 5 (Report)
from ### Mode: implement (default). Embed the refactor report as the
report body. The file change table and acceptance criteria table follow the
standard format so the handoff to code review is seamless.
After the refactoring is complete, proceed to the standard Phase 5 (Report)
and Phase 6 (Handoff to Code Review) exactly as a standard implementation
work item would. The code review gate is mandatory for all refactoring work
items regardless of size — there is no "no review needed" bypass.
### Bugfix Work Items
A work item is a bugfix work item when:
- Its description starts with "Bugfix", "Fix", "修复", "Bug", or "Hotfix".
- It is explicitly tagged `[BUGFIX]` in the node ticket / request.
- The node spec identifies it as a correction of existing behavior
(no new capabilities).
- Its description references a bug report, stack trace, or root cause analysis
from the bugfix workflow's Phases 1–2.
When a work item is a bugfix work item, follow the workflow defined in
Mode: bugfix above with these adaptations:
1. **Understand & Reproduce** (bugfix Phase 1): The scope is the work item
description and the bug reproduction steps captured in requirements.
2. **Isolate Root Cause** (bugfix Phase 2): The root cause may already be
documented in the requirements; verify it against the current codebase.
If the root cause differs, flag a design gap and abort.
3. **Write Regression Test** (bugfix Phase 3): Before fixing, write a test
that fails with the bug's symptom. The test must exercise the exact
condition described in the acceptance criteria.
4. **Fix** (bugfix Phase 4): Apply the minimal surgical fix. The fix MUST
match the design document's component and interface decisions.
5. **Self-Check & Report** (bugfix Phase 5): Run `bun run test:changed`, `bun typecheck`,
`bun oxlint --deny-warnings`. Verify every item in `core/checklists/bugfix.md`.
6. **Produce the implementation report** using the standard Phase 5 (Report)
from ### Mode: implement (default). Embed the bugfix report as the report
body. The file change table and acceptance criteria table follow the
standard format so the handoff to code review is seamless.
After the bugfix is complete, proceed to the standard Phase 5 (Report) and
Phase 6 (Handoff to Code Review) exactly as a standard implementation work
item would. The code review gate is mandatory for all bugfix work items
regardless of size — there is no "no review needed" bypass for pipeline
bugfixes.
### Frontend Work Items
A work item is a frontend work item when:
- Its description starts with "Frontend", "UI", "Component", "Page", "Style",
"前端", "UI", "组件", "页面", or "样式".
- It is explicitly tagged `[FRONTEND]` in the node ticket / request.
- The node spec identifies it as a UI-layer change.
- The work item's component mapping (node `req_refs` + component field in
`{epic-slug}/dag`; historically `{slug}/03-design-08-traceability`) shows
components in `components/`, `pages/`, `views/`, `ui/`, or frontend
framework directories.
- The work item involves `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.css`,
or `.scss` files exclusively (no backend or data-layer files).
When a work item is a frontend work item, follow the workflow defined in
`core/skills/frontend/SKILL.md` with these adaptations:
1. **Parse Context** (frontend Phase 1): The scope is the work item
description, the design sections it references, and the project's
framework/styling conventions. Read neighboring frontend files to absorb
patterns before writing code.
2. **Plan UI Implementation** (frontend Phase 2): Produce a brief
implementation plan covering component structure, props, state variants
(loading/empty/error/edge), and accessibility requirements. Cross-
reference every design specification.
3. **Implement** (frontend Phase 3): Implement in layers — structure → style
→ state variants → interactivity → accessibility pass. Every component
MUST render gracefully in all states.
4. **Self-Check** (frontend Phase 4): Run `bun typecheck`, `bun oxlint --deny-warnings`,
`bun run test:changed`. Verify every item in `core/checklists/frontend.md`.
5. **Produce the implementation report** using the standard Phase 5 (Report)
from ### Mode: implement (default). Embed the frontend report as the report
body. Include state coverage and accessibility verification tables. The file
change table and acceptance criteria table follow the standard format so the
handoff to code review is seamless.
After the frontend implementation is complete, proceed to the standard Phase 5
(Report) and Phase 6 (Handoff to Code Review) exactly as a standard
implementation work item would. The code review gate is mandatory for all
frontend work items regardless of size — there is no "no review needed" bypass
for pipeline frontend work.