docs: sequence a behavior-changing case

[michen00]

What changes, and why

The transform tier's two rules cannot both be followed in the order they are given. corpus/README.md says to produce expected.md by running the tool over input.md rather than by writing it out, and .github/pull_request_template.md:17 asks a case that changes what gets joined to have been "written first and failed first". A key generated from the current tool equals current behavior, so a case built that way passes by construction and pins the behavior the change is meant to replace.

The contradiction is older than the wording that exposed it. CONTRIBUTING.md:31 ("write the failing case, watch it fail, then implement") and CONTRIBUTING.md:35 ("produce those two files by running the tool and reading the diff") have sat four lines apart on main carrying it. #47 mirrored the answer-key rule into the tier that lacked it, which is what made the gap visible in a second place.

What differs is the order, not the rule. For a case that changes what gets joined: write the intended key, watch it fail against the current tool, change both implementations, then run the tool again and confirm its output is what you wrote. What ships is still the tool's output, and the hand-written key exists only long enough to fail. That is the opposite of editing a key to make a test pass — there the key moves to meet the implementation, here the implementation moves to meet the key, and the regeneration is what checks that the intent and the implementation agree.

Both documents carry the rule, so both state the sequence.

This is stacked on #47 because the corpus/README.md sentence it qualifies is added there. GitHub retargets this to main when #47 merges.

Corpus

The corpus is the specification, and both implementations answer to it. Tick what applies.

• This changes no behavior the corpus specifies.
• This changes what gets joined, and a case in corpus/ pins the new behavior. The case was written first and failed first.
• The change makes the tool join more than it did. The section above says what it will not eat.

Documentation of how to write a case. No case, key or harness changes.

Checks

• make check passes, or make test does and this touches no Rust.

make tidy is green, and unwrap-markdown-prose-py --fail-on-change leaves both files alone. Documentation only, no Rust.

🤖 Generated with Claude Code

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can commit Qodo's fix in one click with committable suggestions (GitHub & GitLab)

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.40%. Comparing base (bcd8858) to head (d37ab5b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #65   +/-   ##
=======================================
  Coverage   87.40%   87.40%           
=======================================
  Files           3        3           
  Lines         691      691           
=======================================
  Hits          604      604           
  Misses         87       87           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[qodo-code-review]

PR Summary by Qodo

Clarify corpus workflow for behavior-changing cases

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Clarifies that behavior-changing corpus cases must begin with the intended answer key.
• Requires both implementations to match the key before regenerating and verifying tool output.

Diagram

graph TD
  A["Write intended key"] --> B["Run corpus case"] --> C{"Fails first?"} -->|Yes| D["Change both implementations"] --> E["Regenerate output"] --> F{"Matches intent?"}

Loading

High-Level Assessment

The direct clarification in both contributor-facing documents is appropriate because each independently presents the answer-key rule. A cross-link-only approach would leave one workflow entry point ambiguous and require readers to reconcile the ordering themselves.

Files changed (2) +3 / -1

Documentation (2) +3 / -1

CONTRIBUTING.mdDefine the sequence for behavior-changing corpus cases +1/-1

Define the sequence for behavior-changing corpus cases

• Clarifies that behavior-changing cases start with a deliberately written expected key, fail against current behavior, and then drive changes to both implementations. Requires regenerating output afterward to confirm the implementation matches the intended result.

CONTRIBUTING.md

README.mdDocument test-first answer-key handling +2/-0

Document test-first answer-key handling

• Adds the explicit workflow for cases that change what gets joined. Distinguishes implementation-driven verification from editing an answer key merely to make an existing implementation pass.

corpus/README.md

[Copilot]

🟢 Approval recommended

The changes are documentation-only and consistently reconcile previously conflicting contributor instructions without introducing code or harness risk.

Pull request overview

This PR updates contributor documentation to clarify the correct sequence for writing behavior-changing transform-tier corpus cases (specifically, cases that change what gets joined) so “write failing case first” and “generate keys from tool output” can both be followed coherently.

Changes:

• Clarifies that join-changing cases should be drafted by writing the intended expected.md first, confirming the case fails, then updating implementations and regenerating to verify the tool matches the intended output.
• Aligns this sequencing guidance across both corpus/README.md and CONTRIBUTING.md to avoid contradictory instructions.

File summaries

File	Description
corpus/README.md	Adds an explicit exception/sequence for join-changing cases to reconcile “generate expected output” with “fail-first” discipline.
CONTRIBUTING.md	Extends the same sequencing guidance into the contributing workflow narrative so contributor-facing docs remain consistent.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.