Migration Behavior Reporting

Type: User-Invocable, Agent-Invocable LLM Access: Yes Purpose: Keep migration behavior tests readable to humans and keep the generated migration report aligned with those tests.

Use This Skill When

• You are converting another crates/citum-migrate/tests/*.rs suite into behavior-oriented scenarios.
• You are improving behavior summaries in reviewer-facing migration tests.
• You are adding another migration suite to the generated report.
• You are updating the docs publication path for the migration behavior page.

Do Not Use This Skill When

• You are changing low-level unit tests under crates/citum-migrate/src/ that are not suitable for reviewer-facing behavior coverage.
• You are trying to make the full citum-migrate test inventory into the human report.
• You are expanding engine reporting; use engine-behavior-reporting for that.

Current Report Scope

The published migration report currently covers:

• crates/citum-migrate/tests/date_inference.rs
• crates/citum-migrate/tests/substitute_extraction.rs

Expansion Workflow

1. Pick the next migration suite with clear user-visible behavior. Prefer acceptance-style or reviewer-meaningful migration outcomes over internal transform checks.
2. Rewrite that suite to match the report shape:
   • keep scenario names readable
   • call announce_behavior(...) with one plain sentence per scenario
   • keep setup helpers local and concise
3. Ensure the scenario text describes observable migration outcomes, not implementation trivia. Good: "Conditional title substitutes are preserved only for matching item types." Bad: "Calls OptionsExtractor::extract and asserts a vector length."
4. Add the suite to the migration reporting pipeline:
   • add its binary-to-source mapping in scripts/generate-test-report.py via the wrapper script
   • add it to scripts/migration-test-report.sh only if it belongs in the default published migration report
5. Regenerate the report with ./scripts/migration-test-report.sh.
6. Read target/migration-behavior-report.md or target/migration-behavior-report.html and confirm it is useful to a human reviewer without opening source.

Source Reference Rules

• The report should emit concise repo-relative source references like crates/citum-migrate/tests/date_inference.rs:63-68.
• Do not publish generated source-browser pages.
• Do not add GitHub-specific links.

CI Rule

• Do not lengthen normal PR CI for this feature.
• Keep migration-report publication in main-only or manual docs workflows unless the user explicitly asks for PR-time publication.

Files To Update

• crates/citum-migrate/tests/*.rs
• scripts/generate-test-report.py
• scripts/migration-test-report.sh
• docs/index.html
• docs/reports.html
• docs/README.md
• .github/workflows/compat-report.yml
• .github/workflows/deploy_docs.yml

Validation

For report-only or docs-only changes:

• ./scripts/validate-frontmatter.sh --repo-only --copilot-strict
• ./scripts/migration-test-report.sh
• ./scripts/test-report.sh

For Rust-touching changes in test files or Cargo manifests:

• cargo fmt
• cargo clippy --all-targets --all-features -- -D warnings
• cargo nextest run
• ./scripts/migration-test-report.sh
• ./scripts/test-report.sh

Definition Of Done

• The converted suite is readable on its own.
• The generated report shows behavior bullets, not machine-oriented inventory.
• Source references point to the right file and line range.
• The docs publication path still avoids extending normal PR CI time.