Skip to content

Require agents to follow issue title guidance - #683

Merged
taras merged 1 commit into
mainfrom
docs/issue-title-guide
Sep 1, 2026
Merged

taras merged 1 commit into
mainfrom
docs/issue-title-guide

Conversation

@taras

@taras taras commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Why

Issue titles are primary navigation for open work, but agents had no shared contract for naming outcomes, distinguishing product surfaces, or separating title content from labels and issue bodies.

What changes

Before:

Agents relied on local judgment when creating issues or changing Story and Quest titles.

After:

Agents must read and follow one issue-title guide before creating an issue or changing a Story or Quest title. The guide also defines the refinement interview used for corpus reviews.

Review guide

Start with: .agents/issue-titles.md

Then review:

  1. The outcome, terminology, metadata, and status rules
  2. The completion and overlap audit
  3. The repository-wide instruction in AGENTS.md

How to verify it

  • git diff --check verifies the documentation changes contain no whitespace errors.
  • Read the issue-title instruction in AGENTS.md and confirm it applies to one-off issue creation as well as corpus reviews.

Scope

Included

  • Issue-title and metadata rules derived from the completed open-issue review
  • A repeatable refinement interview for reviewing a set of titles
  • A repository-wide requirement that agents use the guide when creating issues

Intentionally unchanged

  • Existing issue bodies and titles, which were updated during the completed review
  • Executable enforcement or GitHub automation

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

github-actions Bot commented Sep 1, 2026

Copy link
Copy Markdown

PR #683: Require agents to follow issue title guidance

2 files, +209 / -0

Scope

🟡 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.

@taras
taras enabled auto-merge (squash) September 1, 2026 01:20
@taras
taras merged commit 2869309 into main Sep 1, 2026
30 checks passed
@taras
taras deleted the docs/issue-title-guide branch September 1, 2026 01:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant