/diagnose-issue: comment style guidance (question-shaped, link-heavy) (#898)

* /diagnose-issue: require full TAXSIM input mapping when using direct Simulation

Lesson from re-examining taxsim #882: forgetting to pass
tax_unit_childcare_expenses in a direct Simulation situation
zeroed the federal CDCC, which shifted tax_liability_if_not_itemizing
by ~$300 and made it look like Microsim and Simulation produced
different answers. They actually agreed — I was comparing apples to
oranges because the inputs weren't identical.

Step 6 now mandates a TAXSIM-to-PE variable cross-walk before running
a direct Simulation, with a table of the easy-to-miss mappings
(childcare → tax_unit_childcare_expenses, proptax → real_estate_taxes,
mortgage → deductible_mortgage_interest, rentpaid → rent).
Debugging checklist updated to match.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* /diagnose-issue Step 1: treat reporter's claims as hypothesis, verify against output.txt

If the reporter cites a specific PE value, confirm it appears in the
bundle's output.txt before building a diagnosis around it. Reporters
sometimes paste values from a different case; without this check
you can construct a wrong narrative around a wrong number.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* /diagnose-issue Step 9: comment style — question-shaped + link-heavy

Replies to taxsim issues should phrase findings as questions ("Possible
that...?") rather than pronouncements, always link the primary sources
used (statute URL, Rev. Proc. PDF, GitHub permalink to the relevant
PE-US variable), and anchor PE behavior to code rather than assertion.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: PavelMakarchuk

.claude/commands/diagnose-issue.md

@@ -257,6 +257,15 @@ If PE needs a fix, **draft** an issue for policyengine-us with:
 
 **Show the draft to the user and wait for approval before posting.** After posting, cross-link the PE-US issue back from the taxsim issue with a short comment.
 
+#### Comment style (taxsim issues)
+
+Replies on taxsim issues should be **soft, question-shaped, and link-heavy**:
+
+- **Phrase findings as questions, not pronouncements.** "Possible that the hand calc didn't apply X?" beats "Your calculation is wrong because you forgot X." If a number doesn't reproduce, ask whether the case was intended differently rather than asserting the reporter is wrong.
+- **Always link the primary sources you used.** Statute citations → the actual `revisor`/`legis` URL. IRS limits → the relevant Rev. Proc. PDF with page anchor. PE-US logic → a GitHub permalink to the specific variable file. Existing PE-US tracking → the issue/PR number.
+- **Anchor PE behavior to code, not assertion.** Don't write "PE applies X correctly" — write "PE checks X in [`<file>`]<github-link> via `<variable>`."
+- Keep it short and structured. One short paragraph per concern with a bold lead-in (e.g., `**M1CWFC**:`).
+
 ---
 
 ## TAXSIM State Code Reference

changelog.d/diagnose-issue-comment-style.changed.md

@@ -0,0 +1 @@
+Add comment-style guidance to /diagnose-issue Step 9: phrase findings as questions, link primary sources (statute / Rev. Proc. / GitHub permalinks to PE variables), anchor claims to code not assertion.