docs(workflows): draw only each workflow's own steps #198

Merged

claudiomaradonna merged 2 commits from docs/chart-convention into main

2026-11-05 11:53:21 +01:00

motoko commented

2026-11-05 11:50:05 +01:00

Collaborator

Why

fix-bug.md, refactor-code.md, and document-feature.md each
redrew the shared chain (brainstorm through deliver) that
how-it-works.md already draws. A reader had to sort out what each
workflow adds from what every change passes through, and every change
to the chain had to be kept in four charts. Nothing stated a chart's
scope, so the guide's lead ("the charts draw what those files say")
read as each chart drawing its whole flow. #196 already moved
implement-feature.md to charts of its own steps only. This applies the
same rule to the other pages.

We set aside one audit finding. It held that two of fix-bug.md's
labels had no source. In fact they come from .agents/templates/work.md
and diagnosis.md, and they are dropped only because they are not
fix-bug's own.

What changed

The guide's chart legend now states the rule. A change workflow's chart
draws only what its skill adds, meaning its opening steps and the
extension points it fills. The chart joins the chain at a run-change
node or at the phases those extensions fill, and the chain itself is
drawn once in "How a change runs".

fix-bug.md now draws diagnose, the diagnosis, run-change with
in-execute, and the route back to diagnose. document-feature.md
draws the audit and its stop, then run-change. refactor-code.md
keeps its pinning branch and its three extension points. Between them
an edge reads "the chain's phases between", and its "a pin changed"
return stays visible. Every page's prose is unchanged.

How to verify

Open docs/workflows/fix-bug.md, refactor-code.md, and
document-feature.md rendered on the branch. Each chart shows only
the workflow's own steps. On main, each one also draws write-plan,
execute-plan, verify-execution, and deliver.
Open docs/workflows/README.md § Reading the charts. The paragraph
under the legend says where the rest of the chain is drawn.

On the tip these pass: bash tests/verify-agent-config.sh,
bash tests/check-work-folder.sh, .agents/hooks/shellcheck.sh repo,
prettier --check '**/*.md', scripts/verify-agent-config.sh, and
git diff --check main. No test renders the charts.

https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64

## Why `fix-bug.md`, `refactor-code.md`, and `document-feature.md` each redrew the shared chain (brainstorm through deliver) that `how-it-works.md` already draws. A reader had to sort out what each workflow adds from what every change passes through, and every change to the chain had to be kept in four charts. Nothing stated a chart's scope, so the guide's lead ("the charts draw what those files say") read as each chart drawing its whole flow. #196 already moved `implement-feature.md` to charts of its own steps only. This applies the same rule to the other pages. We set aside one audit finding. It held that two of `fix-bug.md`'s labels had no source. In fact they come from `.agents/templates/work.md` and `diagnosis.md`, and they are dropped only because they are not fix-bug's own. ## What changed The guide's chart legend now states the rule. A change workflow's chart draws only what its skill adds, meaning its opening steps and the extension points it fills. The chart joins the chain at a `run-change` node or at the phases those extensions fill, and the chain itself is drawn once in "How a change runs". `fix-bug.md` now draws `diagnose`, the diagnosis, `run-change` with `in-execute`, and the route back to `diagnose`. `document-feature.md` draws the audit and its stop, then `run-change`. `refactor-code.md` keeps its pinning branch and its three extension points. Between them an edge reads "the chain's phases between", and its "a pin changed" return stays visible. Every page's prose is unchanged. ## How to verify 1. Open `docs/workflows/fix-bug.md`, `refactor-code.md`, and `document-feature.md` rendered on the branch. Each chart shows only the workflow's own steps. On main, each one also draws `write-plan`, `execute-plan`, `verify-execution`, and `deliver`. 2. Open `docs/workflows/README.md` § Reading the charts. The paragraph under the legend says where the rest of the chain is drawn. On the tip these pass: `bash tests/verify-agent-config.sh`, `bash tests/check-work-folder.sh`, `.agents/hooks/shellcheck.sh repo`, `prettier --check '**/*.md'`, `scripts/verify-agent-config.sh`, and `git diff --check main`. No test renders the charts. https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64

motoko added 2 commits

2026-11-05 11:50:10 +01:00

docs(workflows): state what a workflow's chart draws de94942480

Nothing said a chart's scope, so three workflow pages redrew the shared
chain that how-it-works.md already draws, and every change to the chain
had to be kept in four places.

Claude-Session: https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64

docs(workflows): draw only each workflow's own steps

Maintenance / checks (pull_request) Successful in 4m4s

Details

Maintenance / checks (push) Successful in 3m46s

Details

4247ee48b8

fix-bug, refactor-code, and document-feature redrew the shared chain.
Their charts now end at run-change, or, for refactor-code, at the three
phases its extensions fill, keeping its pin-changed return in view.

Claude-Session: https://claude.ai/code/session_012CBsgjdkRDt2uVUmT7bj64

claudiomaradonna merged commit 4247ee48b8 into main

2026-11-05 11:53:21 +01:00

claudiomaradonna deleted branch docs/chart-convention

2026-11-05 11:53:25 +01:00

No reviewers

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

claudiomaradonna/agent-foundry!198

No description provided.

Rows
Columns