Formalized, Reviewed, Triaged — A Practitioner's Account, Part II

Source: Dev.to

Hook

The work‑pool schema that runs the paragraf project defines three work types: spec, package, and issue‑bucket. Only two of the three have a defined process.

The first article introduced a methodology that produced a working library. Two parallel improvements happened in the week that followed:

1. A sprint that shipped two new color‑related packages.
2. Formalization of the methodology to handle both spec and package work.

In article‑1 the methodology was a practice; one week later it became a documented process.

Methodology Documentation

docs/
├── methodology.md              # phases, gates, ask‑human triggers
├── methodology-reference.md    # archive procedures, anti‑patterns
├── outer-context.md            # project‑level consistency checker
├── work-pool.md                # work registry + state machine
├── glossary.md                 # defined terms, hierarchy summary
├── dependency.md               # project‑level dependency map
├── io-schemas.md               # project‑level I/O navigation
├── roadmap.md                  # strategy and milestones
├── AI-PRIMER.md                # minimal session bootstrap
│
├── inner-context/[package]/
│   ├── inner-context.md        # role, constraints, package rules
│   ├── io-schema.md            # public types, exported functions
│   ├── dependency.md           # package imports
│   └── decisions.md            # active draft decisions only
│
├── plan/
│   └── workId-package-spec-plan-[YYMMDD-HHMM].md
│
└── archive/
    ├── plan/done/
    ├── plan/cancelled/
    └── decision/[package]-decisions-archive.md

• Each document has a single role.
• methodology.md is the instruction set (four phases).
• outer-context.md provides project‑level consistency checks.
• work-pool.md is the registry with an explicit state machine.
• decisions.md holds in‑flight decisions, which graduate to a one‑line constraint once finalized.

The motivating observation is simple: in article‑1 the methodology survived a rapid iteration cycle, and the new process proved its value when the two color packages shipped under it.

Formalization in Practice

During the sprint, a design reversal occurred: the original choice to import OutputIntent directly into render‑pdf was replaced by a new draft decision documented in decisions.md. The decision lifecycle handled this without ceremony, demonstrating that the formalized process can accommodate reversals gracefully.

• Tests passed.
• End‑to‑end runs went green.

Article‑1 described an audit moment (excuse-me-kemal-I-forked-up.md) when unit tests failed. The subsequent review built on that experience.

Review Process and Findings

The Four Categories of Findings

Five‑Step Review Workflow

1. Whole‑codebase review by Claude Opus – the codebase was uploaded to a review environment.

2. Cross‑check and addition by VS Code Copilot – Copilot added findings, corrected priorities, and narrowed scope.

3. Batched fixes by VS Code Copilot – items were grouped and fixed.

4. GitHub Copilot review on diffs, then Copilot fixes – run three times:

   gh pr view --json reviews,comments \
     --jq '.reviews[].body, .comments[].body' \
     > docs/findings-I.md

   This produced findings-I.md, findings-II.md, and findings-III.md with comment counts of 7, 11, and 6 respectively. Each file was reviewed and the issues fixed.

5. Final structural pass by Opus – the updated codebase returned for a structural and architectural review.

The total—around 105 findings—came from two sources: 81 items from Opus and the remainder from Copilot. A methodology that is written down can be checked against the work it produces.

Issue‑Bucket Gap

The work‑pool schema names three work types: spec, package, and issue‑bucket. While spec and package work have defined processes, issue‑bucket work has none. The type exists as a first‑class entry but lacks a formal lifecycle.

Concrete example: During the review, a finding was produced for @paragraf/render-pdf and @paragraf/compile. The catch happened in the operator’s head, not in the apparatus. This connects directly to the difference between typesetting and typography, and mirrors the “false‑assurance tests” discussed in the table above.

The gap is not a failure of formalization; it reflects the honest limit of any process. Twenty‑two of the original 81 items remain open, but they are not residual—they highlight the need for an explicit issue‑bucket loop.

Conclusion

Two improvements in one week—two new packages shipped under a formalized methodology—demonstrate that the process scales from practice to documented procedure. The lesson extends beyond paragraf: any LLM‑assisted system that survives long‑term development benefits from a clear, written methodology.

The next article in this series will address the issue‑bucket loop once it is closed. The paragraf repository, live demo, and article series are open source:

github.com/kadetr/paragraf