file-issue better titles

deno.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/denoland/deno/main/cli/schemas/config-file.v1.json",
   "name": "@webjam/tools",
-  "version": "1.32.37",
+  "version": "1.32.38",
   "exports": "./src/uptime/cron.ts",
   "tasks": {
     "sheet-music:generate": "deno run --allow-read --allow-write src/sheet-music/generate_docx.ts",

skills/design-issue/SKILL.md

@@ -73,6 +73,8 @@ Replacing a paragraph is not the complete edit. An edit is finished only when th
    | # | Proposed title | Epic / child of | Model tier | Priority | Repo | Tests | Closes when |
    |---|---|---|---|---|---|---|---|
 
+   - **Issue Titles for Project Manager Audience**: Proposed titles in the plan table must be written for a project manager audience (professional, concise, action-oriented, and unambiguous), include the skill or feature scope prefix where applicable (e.g. `skills/file-issue: ...`, `model/venue: ...`), and cite the parent Epic where applicable.
+
 8. **Split out manual steps as pairs**, grouped by gate position in the dependency chain. Manual documentation / UI inspection (e.g. verifying generated Markdown/HTML in Google Chrome) and live demonstration / procedure walkthroughs (e.g. executing real-world steps with a learner or external party) are distinct verification surfaces and must be split into separate standalone pairs/issues. **Issue & Document Title Rule for Manual Steps:** Never include personal names (e.g. "Josh:") in issue titles or document titles. Issue titles must be professional, action-oriented, and role-agnostic (e.g. "Manual verification: ...", "Verification: ..."), with ownership designated exclusively by the `Josh` label or assignment, never embedded as a name prefix.
 9. **Determine the dependency chain** across the planned issues and record it. Where an issue's deliverable is a pointer — "point X at Y" — the plan **names Y concretely**, because an unnamed target hides an ordering: if Y turns out to be something another planned issue creates, the two issues are not independent, and the implementer picks the target after the chain was already declared. Where a load-bearing proof requires implementation work to obtain, sequence that proof FIRST in the dependency chain — never leave it as a late acceptance criterion whose failure would invalidate everything already built on it.
 10. **List every `Needs Design` label change as its own named item** — each removal carrying its 4-part reason.
@@ -95,7 +97,7 @@ Replacing a paragraph is not the complete edit. An edit is finished only when th
 
 Filing delegates to a subagent only when delegating moves the work down a tier (Opus design hands off to a Sonnet subagent; agy already on Flash High files directly itself with no self-delegation). The subagent or session receives the approved plan table and the design document path. It files and reports; it builds nothing.
 
-13. **File in plan order — the epic first, then each child** — invoking `/file-issue` once per issue so the filing rules and their enforcing hook apply to every one. Attach each child to its parent as it goes; the ordering is forced by the parent/child link.
+13. **File in plan order — the epic first, then each child** — invoking `/file-issue` once per issue so the filing rules and their enforcing hook apply to every one. Attach each child to its parent as it goes (and cite the parent Epic in the child issue body); the ordering is forced by the parent/child link.
 
     **Cross-repo children.** GitHub sub-issues exist only within a single repository. Attach every same-repo child natively and do NOT restate it in the epic body — GitHub already renders that list. Name ONLY the cross-repo children in the epic body, under their own heading, and cite each as `repo#number "title"`. Never both: each child appears in exactly one place, or the epic drifts from its own child list.
 14. **Each body carries only scope, build mechanics and repo facts**, plus a pointer to the design document and the instruction to STOP if that path cannot be read. No requirement text is restated.

skills/file-issue/SKILL.md

@@ -141,6 +141,10 @@ that's what following this skill prevents.
     - Edits to shared guardrails, rules, or skill instructions in `AGENTS.md`, `docs/cross-ai-rules.md`, or a skill body (`skills/*/SKILL.md`) must be **purely additive** unless the issue explicitly specifies the retirement, replacement, or deletion of existing rules.
     - Pre-existing rule bullets, rationale, and instructions must never be silently removed, truncated, or clobbered when appending new guidelines.
     - The issue's `## Acceptance criteria` and `## How to test locally` sections must include a named check that proves it (e.g. running `git diff origin/dev -- <file>` to verify that the diff contains no removed lines other than explicitly targeted edits).
+17. **Issue Titles for Project Manager Audience with Skill/Feature Prefix and Epic Citation.**
+    - **Written for a Project Manager Audience**: Issue titles must be professional, concise, action-oriented, and immediately clear to project managers, developers, and stakeholder agents reviewing issues in milestone boards or queues. Avoid vague, generic, or overly terse titles (e.g. avoid bare "fix bug" or "clean up"); state clearly what capability, fix, or requirement is delivered.
+    - **Skill or Feature Scope Prefix**: Where applicable, prefix the title with the specific skill, component, module, or feature path being touched followed by a colon (e.g. `skills/file-issue: ...`, `skills/pr-review: ...`, `model/venue: ...`, `src/uptime: ...`, `venue-mining: ...`, `book-gig: ...`).
+    - **Link/Cite Parent Epic**: When an issue is planned or filed as a sub-issue/child of an Epic, cite the parent Epic by `repo#number "title"` in the issue body (e.g. `## Context` / `Parent Epic: <repo#number "title">`) and link it natively via `--parent <epic_num>` (or GraphQL `addSubIssue`).
 
 ## Citation format (every reference, every time)
 

test/skills_validation.test.ts

@@ -160,6 +160,30 @@ Deno.test("skills/file-issue/SKILL.md contains the three-outcomes guard rule, po
   );
 });
 
+Deno.test("skills/file-issue/SKILL.md contains the issue titles rule for PM audience, skill/feature prefix, and Epic citation (#869)", async () => {
+  const fileIssuePath = `${SKILLS_DIR}file-issue/SKILL.md`;
+  const text = await Deno.readTextFile(fileIssuePath);
+
+  assert(
+    text.includes(
+      "Issue Titles for Project Manager Audience with Skill/Feature Prefix and Epic Citation",
+    ),
+    "skills/file-issue/SKILL.md must contain the numbered rule 'Issue Titles for Project Manager Audience with Skill/Feature Prefix and Epic Citation' in Before you file",
+  );
+  assert(
+    text.includes("Written for a Project Manager Audience"),
+    "skills/file-issue/SKILL.md must require titles written for a project manager audience",
+  );
+  assert(
+    text.includes("Skill or Feature Scope Prefix"),
+    "skills/file-issue/SKILL.md must require skill or feature prefix where applicable",
+  );
+  assert(
+    text.includes("Link/Cite Parent Epic"),
+    "skills/file-issue/SKILL.md must require linking and citing parent Epic where applicable",
+  );
+});
+
 Deno.test("skills/design-issue/SKILL.md contains the both-surfaces rule and refusal table entry", async () => {
   const designIssuePath = `${SKILLS_DIR}design-issue/SKILL.md`;
   const text = await Deno.readTextFile(designIssuePath);