[VALIDATION-1] Inconsistent --dry-run docs between CLI help and compilation guide

[danielmeppiel]

Summary

While reading through docs/src/content/docs/guides/compilation/, I noticed the apm compile --dry-run flag is documented in two places with slightly different behavior descriptions. The CLI command reference says it prints "the diff that would be applied", while the compilation guide says it shows "the deployed primitives that would be touched". These describe the same thing but the wording inconsistency makes it confusing for users trying to understand whether --dry-run actually walks the integrators end-to-end or just lists files.

Repro

1. Run apm compile --help -- see "the diff that would be applied"
2. Open docs/src/content/docs/guides/compilation/index.md -- see "the deployed primitives that would be touched"

Same flag, two descriptions.

Suggestion

Pick one canonical phrasing and use it in both surfaces. Suggest something like: "Show what would change in target directories without writing any files. Each integrator runs in dry-run mode and reports planned actions."

This is a small docs-quality issue. Probably 10 minutes for someone familiar with the docs structure.

Happy to send a PR if a maintainer agrees on the phrasing.

[github-actions]

Triage decision

accept

Proposed labels

area/docs-site
area/cli
type/docs
status/accepted
priority/low
good first issue

Milestone

0.9.4

Suggested next action

Confirm the canonical --dry-run behavior by running apm compile --dry-run on a test project, then submit a PR updating the CLI help text in src/apm_cli/cli.py, the compilation guide at docs/src/content/docs/guides/compilation/index.md, and the canonical CLI reference at docs/src/content/docs/reference/cli-commands.md.

Suggested issue comment

Thanks for reporting this, and for offering to send a PR -- that offer is very welcome.

The inconsistency you found is real. "The diff that would be applied" and "the deployed
primitives that would be touched" describe the same flag through two different mental
models, and for a user reading both surfaces the doubt about --dry-run scope is
legitimate.

We're accepting this as a docs-quality fix. Your suggested phrasing is a good starting
point:

> "Show what would change in target directories without writing any files.
>  Each integrator runs in dry-run mode and reports planned actions."

Before landing on the exact words, please verify against actual behavior:
run `apm compile --dry-run` on a small test project and confirm that the integrators
do run end-to-end (rather than just listing files). That confirmation locks in the
accurate canonical description.

Three surfaces need to agree in the same PR:

1. The CLI help text -- `src/apm_cli/cli.py` (the `--dry-run` flag description)
2. The compilation guide -- `docs/src/content/docs/guides/compilation/index.md`
3. The canonical CLI reference -- `docs/src/content/docs/reference/cli-commands.md`
   (per project convention, this file is the authoritative source; any CLI change
   that is not reflected here is considered incomplete)

If you'd like to go ahead, the change is small and well-scoped. Happy to review
quickly once a draft PR is up.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The issue identifies a real but minor UX friction: apm compile --help reads "the diff that would be applied" while the compilation guide reads "the deployed primitives that would be touched." For a user who reads both, this plants doubt about whether --dry-run runs integrators end-to-end or merely lists files. Per the devx-ux agent rule, CLI help and cli-commands.md must agree in the same PR -- the discrepancy here spans two surfaces (help text and guide). The author's proposed phrasing is accurate and grounded in the package-manager mental model. The implementing PR must verify the phrasing against actual behavior and update all three surfaces simultaneously.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. This is a documentation consistency issue for the --dry-run flag and does not touch any security-relevant surfaces: no lockfile, no marketplace name resolution, no MCP config, no auth, no signing, no path security, no token management. theme/security and theme/governance are not warranted.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author danielmeppiel is a COLLABORATOR with established interaction history on microsoft/apm; no first-time contributor tone adjustments are needed.

Python Architect -- Architecture Reviewer

Not activated -- this is a documentation consistency fix only; no new CLI commands, no schema changes to apm.yml or lockfile, no cross-module design decisions, and no new primitives are proposed. The fix is pick-one-phrasing-update-two-files.

Doc Writer -- Documentation Reviewer

Docs work is the entire scope of this issue. Three surfaces must agree: (1) CLI help text in src/apm_cli/cli.py, (2) compilation guide at docs/src/content/docs/guides/compilation/index.md, and (3) canonical CLI reference at docs/src/content/docs/reference/cli-commands.md. The area/docs-site label covers the guide and reference pages; area/cli is a justified secondary because the CLI help string is one of the two diverging surfaces. The author's suggested phrasing is readable and user-vocabulary-grounded. The implementing PR should run apm compile --dry-run on a real project to confirm behavioral accuracy before standardizing the wording.

APM CEO -- Triage Arbiter

Clean accept. This is a tightly scoped docs-quality issue with no architectural concerns, no security implications, and a contributor already volunteering a PR. The inconsistency is real and causes legitimate user doubt about --dry-run scope. Accepting to milestone 0.9.4 (current active-stream patch). Label set stays within the 6-label cap; no theme/* needed as both area/* labels are pure infra/docs with no product surface implication. Marking good first issue is justified -- estimated at 10 minutes, scoped to three files, and the author explicitly offered to contribute.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/docs-site", "area/cli"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": ["good first issue"],
  "milestone": "0.9.4",
  "next_action": "Confirm --dry-run behavior by running it on a test project, then submit a PR updating the CLI help text, the compilation guide, and the canonical CLI reference in the same changeset.",
  "comment_markdown": "Thanks for reporting this, and for offering to send a PR -- that offer is very welcome.\n\nThe inconsistency you found is real. \"The diff that would be applied\" and \"the deployed primitives that would be touched\" describe the same flag through two different mental models, and for a user reading both surfaces the doubt about --dry-run scope is legitimate.\n\nWe're accepting this as a docs-quality fix. Your suggested phrasing is a good starting point:\n\n> \"Show what would change in target directories without writing any files. Each integrator runs in dry-run mode and reports planned actions.\"\n\nBefore landing on the exact words, please verify against actual behavior: run `apm compile --dry-run` on a small test project and confirm that the integrators do run end-to-end (rather than just listing files). That confirmation locks in the accurate canonical description.\n\nThree surfaces need to agree in the same PR:\n1. The CLI help text -- `src/apm_cli/cli.py` (the `--dry-run` flag description)\n2. The compilation guide -- `docs/src/content/docs/guides/compilation/index.md`\n3. The canonical CLI reference -- `docs/src/content/docs/reference/cli-commands.md` (per project convention, this file is the authoritative source; any CLI change that is not reflected here is considered incomplete)\n\nIf you'd like to go ahead, the change is small and well-scoped. Happy to review quickly once a draft PR is up."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 446.8K · ◷

[github-actions]

Triage decision

accept

Proposed labels

area/cli
area/docs-site
type/docs
status/accepted
priority/low
good first issue

Milestone

0.7.4

Suggested next action

Agree on the canonical phrasing in this thread, then open a PR updating both src/apm_cli/cli.py (the --dry-run help string) and docs/src/content/docs/guides/compilation/index.md in one commit so both surfaces stay synchronized.

Suggested issue comment

Thanks for catching this -- consistency between `--help` output and the docs is a real usability concern and this is a clean, well-scoped report.

The two current phrasings:
- CLI help: "the diff that would be applied"
- Compilation guide: "the deployed primitives that would be touched"

...describe the same behavior but frame it differently, which creates uncertainty about whether `--dry-run` does a full integrator walk or just a file listing. Your suggested canonical phrasing lands well:

> "Show what would change in target directories without writing any files. Each integrator runs in dry-run mode and reports planned actions."

It is precise, it names both the "no writes" guarantee and the "integrators run end-to-end" behavior that distinguishes `--dry-run` from a simple file listing.

**Accepting this as a small docs fix.** The implementing PR should touch two files in one commit:
1. The `--dry-run` help string in `src/apm_cli/cli.py` (or the relevant Click command definition).
2. `docs/src/content/docs/guides/compilation/index.md`.

If you want to send the PR, please go ahead -- the fix is self-contained and should be straightforward to review. You can use `apm compile --help` and the compilation guide page as the before/after verification checklist.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This issue maps directly to a concrete UX pain point: two descriptions of the same --dry-run flag in two authoritative surfaces create genuine ambiguity about what the flag does. A user consulting apm compile --help before reading the compilation guide (or vice versa) encounters a behavioral discrepancy ("diff" vs "primitives that would be touched") that cannot be resolved without reading source code. The author's proposed canonical phrasing correctly captures both the "no writes" guarantee and the "integrators run end-to-end" behavior. Fix scope is bounded: area/cli (the help string) + area/docs-site (the compilation guide). Both must land in the same PR to be effective.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. The inconsistency is purely in prose descriptions of the --dry-run behavior; it does not touch the lockfile, marketplace resolution, MCP config trust model, auth, signing, or any P/G/S surface. No theme/security or theme/governance label is warranted.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a project collaborator (COLLABORATOR association, site_admin) with extensive prior interactions on microsoft/apm; no first-time contributor tone tuning is needed.

Python Architect -- Architecture Reviewer

Not activated -- the fix is a docs-only wording change requiring no cross-cutting design decision, interface change, data model migration, or new primitive; a single PR touching two files is sufficient.

Doc Writer -- Documentation Reviewer

Docs work is explicitly the subject of this issue. area/docs-site should be a primary area label alongside area/cli since both surfaces need updating in the same PR. The author's proposed canonical phrasing ("Show what would change in target directories without writing any files. Each integrator runs in dry-run mode and reports planned actions.") is grounded in APM vocabulary (integrators, target directories) and precise about the two properties users care about: no writes, and a full integrator walk. The suggested comment wording is clear and actionable. Tagging as good first issue is appropriate given the bounded two-file scope and the author's offer to submit a PR.

APM CEO -- Triage Arbiter

Clear accept. The issue is reproducible, scoped to two exact files, has a proposed canonical phrasing, and comes with an offer to PR. No strategic tension: aligning --help output with the docs reinforces APM's "failure mode is the product" principle and the expectation that the CLI and its documentation agree. No theme/* label is required -- this is a pure-infra fix (area/cli + area/docs-site only, no product surface implication). Assigning to the current patch milestone (0.7.4) and marking good first issue to make it easy for a contributor to pick up.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": ["good first issue"],
  "milestone": "0.7.4",
  "next_action": "Agree on the canonical phrasing in this thread, then open a PR updating both src/apm_cli/cli.py (the --dry-run help string) and docs/src/content/docs/guides/compilation/index.md in one commit so both surfaces stay synchronized.",
  "comment_markdown": "Thanks for catching this -- consistency between `--help` output and the docs is a real usability concern and this is a clean, well-scoped report.\n\nThe two current phrasings:\n- CLI help: \"the diff that would be applied\"\n- Compilation guide: \"the deployed primitives that would be touched\"\n\n...describe the same behavior but frame it differently, which creates uncertainty about whether `--dry-run` does a full integrator walk or just a file listing. Your suggested canonical phrasing lands well:\n\n> \"Show what would change in target directories without writing any files. Each integrator runs in dry-run mode and reports planned actions.\"\n\nIt is precise, it names both the \"no writes\" guarantee and the \"integrators run end-to-end\" behavior that distinguishes `--dry-run` from a simple file listing.\n\n**Accepting this as a small docs fix.** The implementing PR should touch two files in one commit:\n1. The `--dry-run` help string in `src/apm_cli/cli.py` (or the relevant Click command definition).\n2. `docs/src/content/docs/guides/compilation/index.md`.\n\nIf you want to send the PR, please go ahead -- the fix is self-contained and should be straightforward to review. You can use `apm compile --help` and the compilation guide page as the before/after verification checklist."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 449.9K · ◷