Fix stale CLI help text and add a rule to keep it current - #39
Merged
Conversation
pyflow --help / bare `pyflow` claimed "Stage 0 skeleton -- no simulation functionality yet" long after Stage 4 landed real numerics and a live-stepping golden demo, and never mentioned --config or how to run a golden demo anywhere the top-level help would show it. Rewrote the top-level description/epilog to describe current capability (phrased so it doesn't need editing every stage exit) and added a run_parser epilog example. Locked in with two new tests (test_main.py, test_cli.py) that assert the stale claim is gone and --config/examples/golden-demos are present, and a dated rule in src/pyflow/CLAUDE.md requiring this text be revisited whenever a subcommand, flag, or golden demo changes. Blast Radius: the two new tests brought the live count to 605, so roadmap.md's and repository-manifest.md's own restated test-count claims needed the same update make check-status exists to catch.
… timeframe claim README.md's Project Status and Current Phase sections still said PyFlow "has completed Stage 3... and is about to begin Stage 4" and pointed a reader at Stage 2's Field Display demo as "the most recent" -- stale since Stage 4 closed (PR #38), caught while auditing the CLI help text for the same kind of staleness. Updated both sections to reflect Stage 4 being complete and Stage 5 not yet started, and repointed the "try the most recent demonstration" command at the Passive Scalar Transport demo. Added a rule in docs/practices.md: README's Project Status/Current Phase sections must be updated in the same change a stage opens or closes, same standing as the existing Quick Start rule, and stale docs found during unrelated work should be fixed on the spot rather than only flagged. Also corrects an inaccurate claim made in this same fix's own prior commit (src/pyflow/CLAUDE.md): the CLI help text was described as having gone stale "long after" Stage 4 landed, when in fact Stage 4 landed within about a day and the closing PR merged under an hour before that claim was written. Reworded to state the actual timeline.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
pyflow --help/ barepyflowdescribed the CLI as a "Stage 0 skeleton -- no simulation functionality yet" long after Stage 4 landed real numerics, PISO, and a live-stepping golden demo, and never mentioned--configor how to run a golden demo anywhere the top-level help would show it (argparse only surfaces a subcommand's own flags under that subcommand's own--help).__main__.py's top-leveldescription/epilogto describe actual current capability, phrased by what the CLI can do rather than by roadmap stage number so it survives a stage exit unedited; added a matching example epilog onrun_parser.src/pyflow/CLAUDE.md: this help text must be revisited whenever a subcommand, flag, or golden demo changes, in the same change (Blast Radius applied to the CLI's own self-description).tests/unit/test_main.py::test_top_level_help_describes_current_capabilitiesand its subprocess-boundary mirror intests/integration/test_cli.pyassert the stale "Stage 0" claim is gone and--config/examples/golden-demosare present.docs/planning/roadmap.md's anddocs/repository-manifest.md's own restated counts needed updating too (exactly whatmake check-statusexists to catch) -- fixed in the same change,docs/planning/status.mdregenerated.Test plan
make lint(pre-commit: whitespace, YAML, codespell, ruff, mypy) -- cleanmake ciin full -- 605 passed, allcheck-*targets clean (check-docs,check-docs-index,check-graph,check-dependency-tree,check-inventory,check-manifest,check-references,check-scenarios,check-status)pyflow --helpandpyflow run --helpoutput for readability🤖 Generated with Claude Code