[taras]

Why

Agents need one issue contract, not separate instructions for titles and
descriptions. Title wording, description clarity, Quest classification, live
status, overlap, and active implementation are decisions about the same issue
and must stay consistent.

What changes

Before:

Agents read a title-only guide. Description guidance and the shared status audit
were not part of the repository rule.

After:

Agents read one issue-writing guide before creating an issue or changing a Story
or Quest title, description, or classification. The guide keeps distinct title
and description rules while sharing the status audit, active-implementation
protection, refinement interview, and completion audit.

Review guide

Start with: .agents/issue-writing.md

Then review:

1. The shared status audit and active-implementation protection
2. The preserved title and Quest metadata rules
3. The new description, evidence, and understandability rules
4. The combined refinement interview and AGENTS.md requirement

Look carefully at:

• The guide preserves accepted implementation contracts while still requiring
  factual status corrections.
• Quest classification changes both the Quest: prefix and quest label.

What must stay true

• Issue titles remain standalone outcome statements — enforced by the title
  rules and checked by retaining the examples and completion scan from the
  merged title guide.
• Descriptions remain durable contracts rather than delivery transcripts —
  enforced by the description rules, story shape, and active-contract boundary.
• Agents have one required entrypoint — enforced by the single link in
  AGENTS.md and checked by the repository reference scan.

How to verify it

• git diff --cached --check reports no whitespace errors.
• rg --hidden -n "issue-titles|issue-descriptions|issue-writing" AGENTS.md .agents README.md
  finds only the new .agents/issue-writing.md reference in AGENTS.md.
• Reading the guide confirms its six Markdown fences are balanced and that the
  title rules from the merged guide remain present.

Scope

Included

• One combined issue-writing guide for titles, descriptions, Quest metadata,
  status, and refinement
• Description rules derived from the completed 34-issue review
• A repository-wide requirement that agents use the combined guide

Intentionally unchanged

• Existing issue titles, bodies, labels, and states
• Executable enforcement or GitHub automation
• Component-description guidance

Generated or mechanical changes

• .agents/issue-titles.md is replaced by .agents/issue-writing.md; the title
  rules remain and the shared material is reorganized around the complete issue.

Scope confirmation

• Every changed file supports the purpose described above.
• Unrelated cleanup and formatting changes are excluded.
• Generated or mechanical changes are clearly identified.
• The description matches the final diff and test results.

[github-actions]

PR #687: Require agents to follow issue writing guidance

3 files, +386 / -208

Scope

🟡 594 lines changed. PRs under 400 receive more thorough review.

🟡 Large PR with no linked issue.

Structural

✅ No structural bloat detected.

Slop

✅ Slop indicators look low.

Static Analysis

✅ Oxlint found no issues.

Correctness

No extraneous code patterns detected.