Skip to content

lidge-jun/codexclaw / plugins/codexclaw/skills/dev-scaffolding

cxc-dev-scaffolding

Verified

Use for project/module setup and docs. Triggers: scaffold, structure audit, architecture docs, API docs, monorepo setup, 스캐폴딩, 새 프로젝트, 새 기능, 구조 점검, 모듈 추가.

references/implementation-log.md

View on GitHub
# Implementation Log (devlog) Routine — the documentation loop inside PABCD

Canonical placement and documentation routine for implementation units.
Numbering and general residence belong to
[Implementation units](../../pabcd/references/implementation-units.md);
folder introduction belongs to ../SKILL.md §2.1.
Read this routine for C2+/multi-phase unit documentation, not every small edit.
cxc-dev §0.1 is canonical for the C0 exemption and existing-unit-only C1 record.

## The unit: one implementation unit = one plan folder

```
devlog/
  _plan/
    YYMMDD_slug/          <- one implementation unit (not one issue, not one commit)
      000_plan.md         <- master plan: objective, constraints, work-phase map
      001_research_*.md   <- research/spec docs (000-009 range)
      010_phase1_*.md     <- phase 1 design at diff-level precision
      020_phase2_*.md     <- phase 2 ...
  _fin/                   <- completed units move here (closure record kept, not deleted)
```

Numbering: decade ranges separate concerns — `000-009` research/specs/MOC, `010-019`
phase 1, `020-029` phase 2, and so on. This repo standardizes on three-digit prefixes
(`000_`, `010_`, `020_`). Never bare semantic filenames (`PLAN.md`, `RCA.md`) — the
numeric prefix is the ordering and the audit trail.

Use the devlog directory printed by `cxc devlog path`: checkout-local in repo/local mode,
outside the checkout in external mode. In none mode, devlog writes are disabled.

## How the routine rides PABCD (the loop)

| Phase | Documentation action | Gate |
|-------|---------------------|------|
| P | CONCRETIZE: write `000_plan.md` (objective, measured baseline, dependency-ordered work-phase map, risks) + research docs `001+`; decade docs for **EVERY roadmap phase** at **diff-level precision** (exact paths, NEW/MODIFY/DELETE, before/after for MODIFY) — DIFFLEVEL-ROADMAP-01 | plan exists as files, not chat |
| A | AUDIT THE DOCS: an independent reviewer checks the plan docs — paths/signatures real, research coverage complete, phases sized, no ownership violations, no contradictions vs research | FAIL → fix docs → re-audit |
| B | Implementation cites the doc it executes; deviations are edited back into the doc BEFORE coding past them | doc and code never diverge silently |
| C | Gate results (commands + tails) recorded into the unit; general SoT docs patched to match the change (SOT-SYNC-01 — recommend creating one if absent) | evidence lives next to the plan |
| D | Attestation/summary appended to `000_plan.md`; on unit completion the folder moves `_plan/` → `_fin/` | durable closure record |

Multi-cycle units: one full PABCD per work-phase; ALL phase design docs are written
to diff-level in the FIRST P (or the design-only Phase-0 pass) —
DIFFLEVEL-ROADMAP-01. P of each later cycle re-verifies its pre-written doc against
the current codebase (stale check) and amends it BEFORE building; it never writes
the doc fresh mid-unit. The attestation log in `000_plan.md` is the continuity spine
— each new P quotes the previous D conclusion from it (see `pabcd` LOOP-CONTINUITY-01).

## Mapping to mainstream developer practice (translation table)

This routine is NOT an issue tracker. Issues are the industry's unit of *tracking*
(small, cheap, closable); this is the industry's unit of *thinking* — the design-doc
lineage. Mature orgs run BOTH and link them. If a collaborator says "devlog isn't
standard", translate:

| This routine | Mainstream equivalent |
|--------------|----------------------|
| `_plan/YYMMDD_slug/` unit folder | Design doc / RFC per feature (Google design docs, Rust RFCs, PEPs) |
| `000-009` research docs | RFC "Motivation / Prior art" sections |
| Diff-level phase docs | Detailed design; kernel patch-series cover letter |
| A-phase doc audit | Design review / RFC final-comment-period — review BEFORE code |
| Evidence in C, attestation in D | CI gate records + review sign-off |
| `_fin/` closure record | Shipped postmortem + changelog entry |
| Hard-to-reverse decisions | ADR (see `dev-scaffolding` §2.1 — separate, immutable) |
| Issue/ticket | Still useful: one issue per unit LINKING to the folder; sub-issues for tracking granularity |

Two deliberate differences from common practice, kept on purpose:
1. **Diff-level precision in the plan** — most design docs stop at architecture;
   agents execute better from exact-path plans, and the A audit becomes mechanical.
2. **Docs gate execution** (A before B) — in many teams design review is advisory;
   here it is a hard gate because the executor (an agent) will otherwise
   confidently build from a flawed plan.

## Reader narrative vs evidence

`000_plan.md` carries the reader narrative: the answer, why, and what changed, per
[Reader documents](../../dev/references/reader-documents.md). Evidence, receipts and
probe logs live under `evidence/` or a numbered evidence doc and are linked from the
narrative, never inlined into it. A reviewer who opens `000_plan.md` should be able
to say what the unit decided without reading a single command transcript.

## Class-scaled documentation

The full master-plan, diff-level roadmap, and doc-audit routine is mandatory for
C4, multi-phase units, and C3 needing persistent contract/architecture evidence.
General unit residence belongs to pabcd's implementation-units reference.
C0/C1 follows cxc-dev §0.1: C0 needs no numbered unit record; C1 records only in
an existing owning unit. Do not create a unit solely for a fast-path record.
Preserve the smallest fresh verification and all safety rules.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall