git:20260826.2055336 to git:20260917.75a2929

+ Use when need to sync session work into GitHub issues OR query status of an

+ existing track across repos. Two modes — write (end-of-session sync: find

+ issues, update body, work-record comment, parent epic + W-label + Project

+ placement, and clean closed tasks from active day/week plans) and read

+ (status lookup across repos with parent/W-label/Project health). Fits the

+ corp-doctor / weekly-planning / weekly-retro operating cycle. Triggers on

+ "/manager", "sync session", "обнови issues", "синкни сессию",

+ "зафиксируй прогресс", "статус задачи", "что по <track>", "есть ли issue по",

+ "track status", "what about <track>".

+ # Manager — bidirectional GitHub issues bridge

+ Part of the Personal Corp framework — running a one-person business through AI agents.

+ Bridges session work and GitHub issues in both directions. GitHub issues are the source of truth for tasks; a GitHub Project board is the source of truth for what's active. Manager has two modes:

+ 1. **Write mode (sync)** — at end of session: read what was done, find existing issues, update with progress + a work-record comment, keep parent / W-label / Project invariants, create new only if nothing matches.

+ 2. **Read mode (query)** — anytime: «what about track X?», «status of Y?» → search across your repos, return condensed state of matching issues with parent epic, labels, Project placement, and last activity.

+ **Manager is the canonical issue workflow.** Do not fall back to a generic issue helper for these operations — manager owns the read-modify-write contract, the invariants, and the Project sync.

+ ## Public distribution boundary

+ Keep this skill reusable: owner, repositories, paths, board IDs and routing come from the user’s local Manager Config. Never bundle session logs, customer examples, private repository references, or a copy of a personal installation.

+ ## Setup

+ Before first use, define this in your project's `AGENTS.md` (preferred) or `CLAUDE.md` (compatibility). If the project has no agent config yet, run `corp-doctor` to create or repair it.

+ ```markdown

+ ## Manager Config

+ ### GitHub owner

+ Your GitHub username or org for issue search:

+ - owner: your-github-handle

+ ### Repos to scan (cross-repo issue search scope)

+ List repos manager should search:

+ - ~/Projects/main

+ - ~/Projects/ops

+ - ~/Projects/marketing

+ ### Tasks index file (optional)

+ Path to your curated current-week index. Manager reads it FIRST before any `gh search` to scope queries:

+ - tasks_index: ~/docs/tasks.md

+ (если файла нет — manager работает без индекса, поиск идёт по всем repos)

+ ### Tasks directory (optional)

+ Path to day/week plan files created by weekly-planning:

+ - tasks_dir: ~/docs/tasks/

+ ### Domain → repo routing

+ | Domain | Repo |

+ |--------|------|

+ | commercial / B2B deals | crm |

+ | product launches | main |

+ | ops / infrastructure | ops |

+ | content | marketing |

+ ### GitHub Projects integration

+ Manager treats Project placement as an invariant (see Iron invariants). Declare your boards:

+ - weekly_project: <number> # cross-repo "everything active this week" board

+ - weekly_project_owner: your-github-handle

+ - status_field: Status # the single-select field that holds the lane

+ - status_in_progress: In progress # option name (or id) for the active lane

+ - domain_projects (optional): # per-domain boards, if you keep them

+ | Domain | Project number |

+ | commercial | <number> |

+ | product | <number> |

+ Cache resolved field/option IDs here once discovered (`gh project field-list <N> --owner OWNER --format json`) so manager doesn't re-fetch them every run.

+ ### W-label convention (optional)

+ - enabled: true

+ - format: W{NN} (ISO week)

+ (если false — manager создаёт issues без weekly labels)

+ ### Standing write authorization

+ - mode: ask-each-time | execute-after-plan

+ (default: ask. execute-after-plan = manager executes writes after showing the brief plan, without separate confirmation)

+ ### CRM integration (optional)

+ - crm_path: ~/Projects/crm

+ - crm_pointer_format: [[<slug>]]

+ (если не используется — секция игнорируется; см. CRM integration ниже)

+ ```

+ `corp-doctor` is the bootstrap/repair skill for this config. Title-type metadata is NOT configured here: it lives in labels, the parent tree, and Projects (see Issue title convention).

+ ## Iron invariants

+ Every issue manager touches MUST satisfy the base three; an active / current-week issue must additionally satisfy the Project and work-record invariants:

+ 1. **W-label** (current or future week, or the date of a specific dated event) — if W-label convention enabled in config. If the label doesn't exist in the repo — create it.

+ 2. **Parent epic** — exactly one parent via GitHub Sub-issues API. Any issue that isn't itself an epic must have a parent. See "Parent epic rules" below.

+ 3. **Track differentiation via title + epic membership** — no track-labels (`<track-slug>`, `<client>-deal`). Track is recognized by title text and epic membership.

+ 4. **Project placement** — an active / current-week issue must be present on its domain Project board (if you keep one) AND on the global weekly Project. A W-label without Project placement = `Project drift`.

+ 5. **Project-visible parent** — for an active / current-week child, one `parent_issue_url` is not enough. The visible root epic must itself be in the relevant Project view with a non-empty status lane.

+ 6. **Work-record comment** — in write mode, only when REAL work happened on the issue this session: a mandatory timeline comment summarizing what was done + commit links. Changing status / label / Project placement does NOT replace it. Pure mechanical re-label / Project-fix with no content work = no comment.

+ Without these — the issue isn't tracked correctly. If no parent epic exists in any repo — manager raises this in proposal and offers to create or pick an existing one, **before** sync. Never leaves orphan issues.

+ ## Mode resolution

+ ```dot

+ digraph mode {

+ "User invocation" [shape=box];

+ "Has session artifacts to sync?" [shape=diamond];

+ "WRITE mode" [shape=box];

+ "READ mode" [shape=box];

+ "User invocation" -> "Has session artifacts to sync?";

+ "Has session artifacts to sync?" -> "WRITE mode" [label="yes — update issues by what was done"];

+ "Has session artifacts to sync?" -> "READ mode" [label="no — query like 'what about X', 'status Y'"];

+ }

+ ```

+ **Signal for write mode:** user said «sync session», «зафиксируй», «обнови issues», OR invoked `/manager` without args at end of session, OR explicitly listed artifacts/changes.

+ **Signal for read mode:** user asked a question about state — «what about», «status», «есть ли», «какие issues по».

+ **Bare `/manager` invocation:** infer artifacts from current conversation context — what tracks were touched, what files were modified/created, what decisions were made. Do NOT ask user to re-list everything. Form brief execution plan (5-15 lines), then execute under the configured authorization mode.

+ **Do NOT use manager for:** creating ideas without artifacts (that's brainstorming); closing an issue without explicit user instruction; batch CRM updates (that's a CRM skill, not manager).

+ ## Output language

+ Output language matches the user's input language and project conventions. Technical tokens remain as-is and are not translated: issue names (`<repo>#<N>`), labels (`W18`, `retro:W17`, `backlog`), commands (`gh issue comment`), file paths, original English titles of issues in quotes.

+ ### Issue-title language

+ New issue titles (and renamed titles) follow the user's locale — match the language convention of the project. English is allowed only as a proper noun: product name, repo name, brand, API name, public upstream term (`GitHub`, `Telegram`, `LMS`, `PRD`, `E2E`). English action verbs and generic filler phrases in titles are forbidden:

+ - ❌ `delivery track`, `launch/funnel`, `follow-up`, `workshop prep`, `handoff`, `rollout package`, `topic TBD`, `date TBD` (as English filler when the project language is not English)

+ All narrative elements in issue titles, body headers, and proposal text follow the project's locale. Technical tokens (`repo#N`, label names, CLI commands, file paths, quoted original titles of existing issues) stay as-is.

+ ## Sources of truth (read every run)

+ 1. **`$TASKS_INDEX_PATH`** (if configured) — current week index. Source for: what's hot this week, what tracks are active, repo pointers for each track. Read FIRST to frame the session.

+ 2. **`$TASKS_DIR/WNN/YYYY-MM-DD.md`** (if configured) — current day plan. Source for: what the founder is actually doing today. Manager may patch it during write sync when touched issues change state.

+ 3. **GitHub issues across `$YOUR_OWNER/*`** — authoritative for individual tasks. Search via `gh search issues --owner $YOUR_OWNER` or batched GraphQL (see below).

+ 4. **GitHub Project board(s)** — authoritative for what's active this week and in which lane.

+ 5. **CRM artifacts** (if CRM integration enabled in config) — meeting cards, opportunity cards, person cards. NOT a substitute for a GH issue, but the linkage anchor: every comm-related issue body must include a CRM pointer.

+ ### Planning / retro cycle

+ Manager participates in the cycle, it does not replace it:

+ - `weekly-retro` reviews the closing week, resolves carry-over, and produces evidence-backed outcomes/backlog.

+ - `weekly-planning` curates `tasks.md`, `tasks/WNN/README.md`, and day plans for the new week.

+ - `manager` keeps GitHub issues, Projects, parents, W-labels, work-record comments, and touched day-plan rows consistent during actual work.

+ When a manager sync changes task state, it must keep the visible plan aligned with that state. If manager closes an issue, the closed issue must not remain as an active P0/P1 row in the current day plan or week index.

+ ## When to use vs when NOT

+ **Use (write mode):**

+ - User says "sync session" / "/manager" / "обнови issues по тому что сделал"

+ - End of working session with concrete artifacts (CRM updates, meeting cards, code commits, docs)

+ **Use (read mode):**

+ - Start or middle of session — user asks «what about <track>», «status», «is there an issue for»

+ - Need cross-repo state of a track without manually grepping

+ - Before deciding next step — check what's already open

+ **Do NOT use:**

+ - For creating new ideas without artifacts — use brainstorming

+ - For closing issues without explicit user instruction (see Common mistakes)

+

+ ## Pre-flight (both modes) — HARD PRECONDITION

+

+ Pre-flight MUST run before any `gh search`, `gh issue`, or other GH command. No exceptions.

+

+ Keep pre-flight silent and minimal. Do not dump tasks index content, full git status, or label catalogues into chat. Read what you need internally, surface only what changes the proposal. **Output budget for pre-flight: 0 lines.**

+

+ 1. **Read `$TASKS_INDEX_PATH` FIRST** (if configured). This is the curated index of current-week priorities + active tracks + repo pointers. Without it, search is shotgun (random keywords) instead of targeted.

+ 2. **Snapshot the weekly Project once per run** with an explicit high limit (the default page truncates large boards):

+ ```bash

+ gh project item-list <WEEKLY_PROJECT> --owner $YOUR_OWNER --format json --limit 1000 > /tmp/manager-proj.json

+ ```

+ 3. **Task drift guard.** If the current day or week plan contains an active task row with no `repo#N` GitHub issue reference → surface as `Task drift: <row> — no GitHub issue`. In read mode: report only. In write mode: find an existing issue or create one (then it carries the iron invariants).

+ 4. Check git status of relevant repos (silently). If specific artifacts referenced in session are uncommitted, mention only those by name in proposal.

+ 5. Compute current ISO week if tasks index "Updated" line is stale (>7 days) or absent.

+

+ **Run independent `gh` reads in parallel** — multiple Bash calls in a single message. Run sequentially only when the output of one call is required as input for the next.

+

+ ### Red flag: skipping tasks index

+

+ If you're about to run `gh search issues` without first reading `$TASKS_INDEX_PATH` (when configured) — STOP. You're about to do shotgun search instead of using the Project/track index that already exists.

+

+ ## Write mode algorithm

+

+ ```dot

+ digraph manager_write {

+ "Infer artifacts from conversation" [shape=box];

+ "Silent pre-flight + cross-repo search" [shape=box];

+ "Brief execution plan (5-15 lines)" [shape=box];

+ "Hard blocker / ambiguous write?" [shape=diamond];

+ "Execute (body, comment, labels, Project)" [shape=box];

+ "Brief result report" [shape=box];

+

+ "Infer artifacts from conversation" -> "Silent pre-flight + cross-repo search";

+ "Silent pre-flight + cross-repo search" -> "Brief execution plan (5-15 lines)";

+ "Brief execution plan (5-15 lines)" -> "Hard blocker / ambiguous write?";

+ "Hard blocker / ambiguous write?" -> "Execute (body, comment, labels, Project)" [label="no"];

+ "Hard blocker / ambiguous write?" -> "Ask concise question / proposal" [label="yes"];

+ "Execute (body, comment, labels, Project)" -> "Brief result report";

+ }

+

+ In write mode, for each touched issue:

+

+ 1. Update the **body** (default channel — not a comment): refresh `Status` / `Next` + a dated entry in `## Updates`.

+ 2. Add the **work-record comment** (Iron invariant 6) — only if real work happened: what was done this session + `refs`/SHA.

+ 3. Ensure **W-label + parent (Sub-issues API) + Project placement**, and set the Project status lane to `In progress` (see Project status sync).

+ 4. Record **commit↔issue linkage** (see below).

+

+ **Authorization mode** (from your `AGENTS.md` / `CLAUDE.md` config):

+

+ - `ask-each-time` (default): after the plan, ask "execute?" before any GitHub write.

+ - `execute-after-plan`: after the silent pre-flight and brief execution plan, execute scoped GitHub writes without asking a separate confirmation. Still run pre-flight, search existing issues, preserve invariants, and report exactly what changed.

+

+ Either mode: ask before writing when the write is genuinely ambiguous or risky — no suitable parent epic, uncertain repo/track ownership, public-repo privacy risk, destructive/bulk changes, closing an issue whose scope is not clearly completed, or conflicting evidence.

+

+ ### Commit ↔ issue linkage

+

+ 1. Every commit in a session should carry a trailer: `refs $YOUR_OWNER/<repo>#N` (or `closes $YOUR_OWNER/<repo>#N` if the commit fully closes the scope). GitHub shows a backlink in the issue timeline — works cross-repo.

+ 2. The dated entry in `## Updates` lists short SHAs of commits from each touched repo this session: `(code: <repo-A>@9a8ff92, <repo-B>@6fb5b26)`. An issue with no SHA when commits exist = incomplete sync.

+ 3. Collect SHAs via `git log --oneline -10` per touched repo before writing the Updates entry.

+ 4. **Artifact must be committed and pushed BEFORE being linked.** The user reads everything via web GitHub — an uncommitted local file does not exist for them. Links in body/report must be clickable GitHub URLs, not `~/...` local paths.

+

+ ### Planning artifacts (PRD / plans / diagrams)

+

+ When a session produces a PRD, plan, or diagram: the full content belongs in the **issue body** — context, decision table, mermaid diagrams (GitHub renders them inline), schema, MVP slices, out-of-scope, open questions — not a link to a file. A local md file can exist as a working copy; if they diverge, the issue body is the source of truth. Any file link from the body is a clickable GitHub URL pointing to an already-committed-and-pushed version, never a local path.

+

+ ## Read mode algorithm

+

+ 1. Resolve query subject — track name, person, repo, issue number, time window.

+ 2. Run cross-repo search (multi-key) — single `gh search issues` for simple tracks, batched GraphQL for 3+ keys (see below).

+ 3. **Filter false-positives** — drop matches where keyword overlap is incidental (e.g. issue tagged `W18` but unrelated to the queried track). See "False-positive surface" below.

+ 4. For true matches, pull live state in one batched GraphQL call: title, state, labels, parent (Sub-issues API), `projectItems` with status lane, last activity. Prose is not evidence — use live reads.

+ 5. **Resolve track epic** — find the parent epic. Pull `sub_issues_summary` — note `total`, `completed`, `percent_completed` + epic's own `state`.

+ 6. Cross-reference tasks index — does the track appear in the current-week priority list? If yes, mark as "🔥 hot W{NN}". Verify the index row for drift: referenced issue CLOSED, scope mismatch, or implied open work that no longer exists.

+ 7. Output: condensed table (with a Project column) + open questions + "what's NOT covered yet" gaps + drift surface. Read mode never writes to GitHub.

+

+ ### Live Project state reads — batched GraphQL

+

+ When surfacing or correcting Project placement, batch up to ~20 issues in one GraphQL call via aliases:

+

+ ```bash

+ gh api graphql -f query='

+ query {

+ i1: repository(owner:"$YOUR_OWNER", name:"<repo1>") { issue(number:<N1>) { ...IssueState } }

+ i2: repository(owner:"$YOUR_OWNER", name:"<repo2>") { issue(number:<N2>) { ...IssueState } }

+ }

+ fragment IssueState on Issue {

+ number title state url

+ labels(first:20){nodes{name}}

+ parent { number title repository { nameWithOwner } }

+ projectItems(first:10){nodes{ id project { number title } fieldValueByName(name:"Status"){ ... on ProjectV2ItemFieldSingleSelectValue { name } } }}

+ }' | jq -r '(.data // {}) | to_entries[] | .value.issue | select(. != null)

+ | "\(.number) \(.title) [\([(.labels.nodes // [])[].name]|join(","))] parent=\(.parent.repository.nameWithOwner // "—")#\(.parent.number // "") projects=\([(.projectItems.nodes // [])[] | "\(.project.title):\(.fieldValueByName.name // "empty")"]|join(" | "))"'

+ Notes: pipe into a separate `jq`, **not** the `--jq` flag (see the CRITICAL note in the batched-search section — when a GraphQL response carries `errors`, `gh` ignores `--jq` and dumps the raw body). `parent` is the Sub-issues API parent; `projectItems[].fieldValueByName.name` is the status lane. Result is at `.data.<alias>.issue` — don't forget the `.issue` level in jq. Single-issue fallback: `gh issue view N -R $YOUR_OWNER/<repo> --json projectItems` — `.projectItems[].status` is an object; read `.status.name`, not `.status`. List epic children: `gh api repos/$YOUR_OWNER/<repo>/issues/<EPIC_N>/sub_issues --jq '.[] | {number, title, repository_url}'`.

+ ### Parent-proof ambiguity

+ When verifying parent visibility: check both the child's `parent_issue_url` AND the parent's `/sub_issues` endpoint. If child-side parent reads as `null` but parent `/sub_issues` lists the child, report `parent proof: parent sub_issues ✓; child API ambiguous` — not `parent missing`. The two API surfaces can disagree transiently.

+ ### Related context, not hierarchy

+ Build a `Related` context list only for true matches with a distinct scope: a separate task, contextual reference, dependency, cross-repo artifact, or historical task. Filter out parent/child links already expressed through the Sub-issues API — those are already visible in the hierarchy column. Do not duplicate API-expressed structure as `Related` prose.

+ ## Search for existing issues — how

+ For each artifact or query subject, search by **multiple keys** to avoid missing matches. For simple unambiguous tracks (single-keyword) one query is enough — escalate to multi-key only when first query returns 0 or 5+ matches:

+ ```bash

+ gh search issues --owner $YOUR_OWNER <key> --json repository,number,title,labels,state,updatedAt

+ ```

+ **`--state` accepts only `open` or `closed` — the value `all` is invalid and errors out.** To cover both states, just omit `--state`: one call returns open and closed together. Never run two queries (open + closed) — that wastes the scarce REST quota (30/min).

+ **Keys to try (per artifact/subject):**

+ - Person name + slug (different transliterations): `"<person-name>"`, `<handle>`, `<filename-slug>`

+ - Company / track: `<track-A>`, `<track-B>`, `<client>`

+ - Telegram/social handle if mentioned: `<handle>`

+ - Filename slug from any CRM artifact: `<opportunity-slug>`

+ **Match acceptance criterion:** issue title or body references the same person/company/track AND scope of work overlaps. If 2+ candidates match — pick the most specific one and link the others as `Related`.

+ ### Batched GraphQL search (3+ keys)

+ When multi-key search needs 3 or more queries, batch them in a single GraphQL call to avoid the REST Search API rate limit (30 req/min):

+ ```bash

+ gh api graphql -f query='

+ query {

+ s1: search(query:"user:$YOUR_OWNER is:issue <term1>", type:ISSUE, first:20){ nodes { ... on Issue { number title state url repository{nameWithOwner} labels(first:10){nodes{name}} updatedAt } } }

+ s2: search(query:"user:$YOUR_OWNER is:issue <term2>", type:ISSUE, first:20){ nodes { ... on Issue { number title state url repository{nameWithOwner} labels(first:10){nodes{name}} } } }

+ }' | jq -r '(.data // {}) | to_entries[] | .key as $k | (.value.nodes // [])[] | select(.number != null)

+ | "\($k) \(.state) \(.repository.nameWithOwner)#\(.number) \(.title) [\([(.labels.nodes // [])[].name]|join(","))]"'

+ ```

+ Omit any `state:` qualifier — one alias returns both open and closed. Adding `state:open` silently drops closed issues (e.g. a closed epic), forcing a wasteful second batch.

+ **CRITICAL — pipe into a separate `jq`, NOT the `--jq` flag.** This is the #1 cause of recurring crashes in this skill:

+ - When a GraphQL response carries an `errors` array (one failed alias, or a totally broken query), `gh api graphql` **ignores the `--jq` flag entirely**: it dumps the raw JSON body to stdout plus a short error to stderr, exit 1. The `(.data // {})` guard inside `--jq` never runs — the flag is bypassed.

+ - A total failure → body is `{"errors":[...]}` with no `data` key. Any downstream `d['data']` (Python) throws `KeyError: 'data'`.

+ - So always `gh api graphql -f query='...' | jq -r '(.data // {}) | ...'`. The raw body (with `data`, or `errors`-only) flows from stdout into `jq`, the `(.data // {})` guard runs on the body: live aliases print, failed ones are skipped, a total failure yields empty output with no crash. The `gh` error stays visible on stderr for debugging.

+ - **Never parse the response with a Python one-liner (`python3 -c "d['data']..."`).** If Python is unavoidable, use `d.get('data', {})`, never `d['data']`.

+

+ **Required jq guards** (without them the expression crashes on `cannot iterate over: null`):

+ - `(.data // {})` **first** — on an `errors`-only body `.data` is `null` and `to_entries[]` crashes; `// {}` yields an empty object

+ - `(.value.nodes // [])` and `(.labels.nodes // [])` — an alias or field can return `null`

+ - `select(.number != null)` — drops empty `{}` objects from non-Issue nodes

+ - `is:issue` in each query string — excludes PRs

+

+ **Partial errors:** with `| jq`, a failed alias is simply absent from the output and the live ones print. Don't blindly retry the whole batch — if needed, read `.errors` in a separate pass (`... | jq '.errors'`), then drop/fix the failed alias.

+

+ **Why:** `gh search issues` is the REST Search API, limited to 30 req/min — multi-key runs of 15-20 searches throttle. GraphQL `search()` counts against the 5000 points/hour GraphQL limit and batches efficiently. Owner qualifier in GraphQL is `user:$YOUR_OWNER` (not `--owner`).

+

+ ## False-positive surface (read AND write mode)

+

+ Search by W-label or generic terms can return issues that **share a label but aren't on this track**. Example: `<repo>#1` returned for `<track-A>` query because both have `W18` label.

+

+ **Rule:** if a search match's title/body has no overlap with the queried track besides W-label or other generic label — it's a false positive. Drop it from results, surface in report under `IGNORED (false positives)` so user can confirm.

+

+ IGNORED (false positives):

+ - <repo>#1 — surfaced via W18 label match, but track = <unrelated track>

+ Don't silently filter — show what was filtered and why, in case user spots a real link manager missed.

+ ## Parent epic rules

+ Every issue (except the epic itself) must have **exactly one** parent via GitHub Sub-issues API. This is machine-readable track differentiation — replaces track-labels and stale markdown pointers in body.

+ ### What counts as an epic

+ - An issue that has sub-issues (counter `N / M` shown at top)

+ - Title typically contains track scope (`<program>: <partner> — overview`, `<deal> — overview`, `<product> — delivery <version>`)

+ - An epic itself does NOT have a parent — it's the root of the tree

+ - A working epic typically has `total >= 1`, but a new root issue with a clear track scope may be proposed and used as an epic before its first sub-issue, provided the user confirms the scope (bootstrapping a new track).

+ ### One epic per issue

+ GitHub supports only one parent via Sub-issues API. This matches: «one track — one hierarchy». If a task seems to relate to two tracks — reconsider scope: probably split into two issues, OR it's an aggregate issue (see below).

+ Do not use markdown `Parent: #N`, `Epic: #N`, `Belongs to: #N` in body when parent is set via API — it's a duplicate that goes stale. Parent is stored via the Sub-issues API only.

+ ### Resolve epic — algorithm at creation / sync

+ 1. **Search for an existing epic** for the track via cross-repo search; verify candidates have non-empty `sub_issues_summary.total`.

+ 2. **Canonical mapping by domain** (configure per your business in `Domain → repo routing`):

+ | Track domain | Epic lives in |

+ |--------------|---------------|

+ | Educational program / partnership | teaching domain repo |

+ | B2B deal / multi-lane commercial track | crm / commercial repo |

+ | Product launch | the product's own repo |

+ | Research initiative | research repo |

+

+ 3. **If no epic exists** — manager raises in proposal: «no epic for track X, do you want one?». Never creates an issue without a parent silently.

+ 4. **When creating a sub-issue** via API:

+

+ ```bash

+ CHILD_ID=$(gh api repos/OWNER/REPO/issues/CHILD_NUMBER --jq '.id')

+ gh api -X POST repos/EPIC_OWNER/EPIC_REPO/issues/EPIC_NUMBER/sub_issues -F sub_issue_id=$CHILD_ID

+ ```

+

+ ### Aggregate parent for cross-track issues

+

+ If an issue covers 2+ sibling tracks, scopes, or deliverable classes, classify it as an **aggregate issue** before assigning a parent. Do not attach it to the first matching subject epic if that would make another sibling scope invisible.

+

+ **Signals of an aggregate issue:**

+ - Title/body explicitly spans multiple sibling scopes: `product + sales`, `strategy + delivery`, `pilot + docs`, `launch + ops`.

+ - Issue lives in an aggregate/reporting repo while the subject epics live in their owner repos.

+ - Body talks about weekly review, close/kill decision, forecast, pipeline, operating review, portfolio snapshot, or cross-repo coordination.

+ - Issue updates a shared index, forecast, heartbeat, dashboard, or plan — not a single concrete deliverable.

+

+ **Algorithm:**

+ 1. Find the subject epic for each sibling scope.

+ 2. Find a repo-local aggregate epic: `forecast`, `pipeline`, `portfolio`, `weekly review`, `operating review`, `coordination`, `umbrella`.

+ 3. If found — attach the issue there. In plan/report write `parent: aggregate`.

+ 4. If none exists — surface a proposal: create an umbrella issue OR split into separate child issues under each subject epic.

+ 5. Never write one issue as a child of two epics; GitHub parent is exactly one.

+

+ In read/write output, distinguish parent types explicitly:

+ - `parent: track` — a specific subject-domain epic

+ - `parent: aggregate` — forecast / pipeline / portfolio / operating umbrella

+ - `parent: runtime` — a published / runtime layer epic

+ - `parent: unknown` — parent not yet found or requires user decision

+

+ ### Project-visible root

+

+ Manager distinguishes three parent concepts:

+

+ - **API parent** — direct parent from the GitHub Sub-issues API (`parent_issue_url`).

+ - **Visible root** — nearest parent / track-overview / umbrella issue that should appear in the current Project view and under which the user expands the tree.

+ - **Historical / backlog grandparent** — upper strategy parent that may remain outside the weekly Project view when the visible root already has a W-label and non-empty status lane.

+

+ **Rules:**

+ 1. If an active / current-week issue has no sub-issues and is a child delivery/action issue, its API parent or visible root must be in the Project with a non-empty status lane.

+ 2. If an issue is itself a track overview / session parent / umbrella (`sub_issues_summary.total > 0`) and is already visible in the Project, its backlog/strategy grandparent does not need to appear in the weekly Project. Report as `parent: historical/backlog`.

+ 3. If a child has `parent_issue_url` but the parent item is absent from the Project view, surface as: `Project divergence: parent epic not visible`.

+ 4. If the child-side API shows `parent: null`, verify by checking the likely epic's `/sub_issues` list. If the child is listed there, treat it as proof — but note `parent proof: parent sub_issues` (GitHub may read hierarchy asymmetrically).

+ 5. If the Project view filters by repo or type such that the parent cannot physically appear, report `Project view limitation` and do not reparent the child.

+

+ ### Related issues — body section

+

+ `Related` / `Related issues` in the body is for contextual cross-links only. It never creates hierarchy.

+

+ - Hierarchy lives only in the GitHub Sub-issues API (`parent_issue_url`, `sub_issues_summary`).

+ - Related links are for contextual references, isolated dependencies, cross-repo artifacts, and historical tasks.

+ - The Related block can be deleted without losing owner, W-label, Project placement, or the sub-issues tree.

+

+ **Forbidden inside a Related block:** `Parent: #N`, `Epic: #N`, `Belongs to: #N`, manual child/subtask lists, status mirror, next-step mirror, W-labels, Project placement cues, checklist state.

+

+ **Body format:**

+ ```markdown

+ ## Related

+

+ - <repo>#N «human-readable title» — brief reason for the link

+

+ **Verified:** YYYY-MM-DD by manager

+ ```

+ Max 3 bullet links + one `Verified` line. On each body sync, rewrite from live search — do not append infinitely.

+

+ **Before writing a body that contains a Related section — live-verify every referenced issue:**

+ ```bash

+ gh issue view N -R OWNER/REPO --json title,state,url,labels,updatedAt

+ gh api repos/OWNER/REPO/issues/N --jq '{parent: .parent_issue_url, sub_summary: .sub_issues_summary}'

+ ```

+ For active / current-week related refs, also check `projectItems`.

+

+ If any ref is missing, closed, parentless, points to another track, has a stale W-label, or would leak private/CRM data into a public repo — surface `Related links divergence` and remove or report before writing the body. For public repos: do not copy private titles, CRM slugs, local paths, personal handles, payment facts, or private URLs — use a safe public label like `private CRM issue — context only` and keep the exact private pointer in a private repo/report.

+

+ ### No track-labels

+

+ Track-labels (`<track-slug>`, `<client>-deal`) are NOT created. Track differentiation goes through title + epic membership. Existing legacy track-labels are not deleted (they're history), but no new ones are created. Cross-repo navigation by track = epic's sub_issues + Project board, not label filter.

+

+ ### Verification before sync

+

+ Before `gh issue edit` / `gh issue create` the agent MUST check the existing issue's parent and, for active issues, its Project placement:

+

+ ```bash

+ gh api repos/OWNER/REPO/issues/N --jq '{parent: .parent_issue_url, sub_summary: .sub_issues_summary}'

+ ```

+

+ Surface in proposal which issues are missing a parent and which epic is proposed for each.

+

+ ## Project status sync (write mode)

+

+ New issues start in the configured backlog lane. The first proposal, draft, specification, or decision counts as work: save the substantive draft in the issue body and move it to the configured active lane.

+

+ In write mode, when the user actively worked on an issue in the current session, manager **must** set the Project status lane to `In progress` on all primary/child issues touched in:

+

+ - The global weekly Project

+ - The domain-specific Project board for the track, if the issue already lives there

+

+ **Rules:**

+ 1. Only update issues that manager updated or created in this sync, plus their visible parent if the parent is also in the current day plan.

+ 2. Do not set `In progress` on historical/backlog issues with no work in this session.

+ 3. Do not downgrade `Done` or `In review` without explicit user signal.

+ 4. If the item is not yet in the Project — run `gh project item-add` first, then `gh project item-edit` to set status.

+ 5. If the parent/session issue of a child is in the day plan and the child is active today — also move the parent to `In progress`.

+

+ ```bash

+ # Step 1 — get item id (from item-add output or item-list snapshot)

+ # Step 2 — get field and option ids (cache these in your config)

+ gh project field-list <PROJECT_NUMBER> --owner $YOUR_OWNER --format json

+ # Step 3 — set status lane

+ gh project item-edit \

+ --id <PROJECT_ITEM_ID> \

+ --project-id <project-id> \

+ --field-id <status-field-id> \

+ --single-select-option-id <in-progress-option-id>

+ ```

+

+ For each domain board, read its field list first — lane names may differ (`In progress` vs `In Progress` vs `Active`).

+

+ **Project drift rules:**

+ - Issue in Project with empty Status field → surface as `Project drift: status lane empty`.

+ - If a GraphQL/rate-limit error blocks the status edit → report `Project drift: placement ok, status lane pending` and do not claim full repair.

+

+ ## Plan cleanup on close

+

+ When manager closes an issue in write mode, it must remove that issue from active planning surfaces in the same sync:

+

+ 1. Read `$TASKS_INDEX_PATH`, current week README, and today's day file if configured.

+ 2. If the closed issue appears as an active P0/P1 row, remove the row or replace it with the next open child issue under the same parent.

+ 3. If the closed issue appears in a weekly/index issue list, remove it when no open work remains for that scope. If the parent remains active, keep the parent and open children.

+ 4. Do not delete historical retro/outcomes evidence. Append a note only when the plan file has a current "Done / Closed today" section; otherwise keep the active plan clean.

+ 5. In the result report, show the cleanup explicitly: `removed closed issue from day plan: repo#N`.

+

+ If manager did not close the issue itself, read mode reports drift only. Do not clean plans for a closed issue unless the current sync is explicitly doing closure or the user asked for cleanup.

+

+ ## W-label rules

+

+ (Skip this section if W-label convention is disabled in your config.)

+

+ ### Current-week resolution

+

+ 1. Read tasks index first line under your "Updated" marker — canonical signal for current week.

+ 2. Compute ISO week from `date '+%V'` if index is stale (>7 days).

+ 3. Map to label format: `W{NN}` (zero-padded only if existing labels in repo are zero-padded — check repo first).

+

+ ### Dated issues — W-label from the event date

+

+ For issues whose title/body/calendar contain a specific event date (a session, live event, workshop, deadline), the W-label is computed from **that event date**, not the current sync date.

+

+ - `<person> S2 — prep and deliver session (29.05)` on 2026-05-29 gets `W22`.

+ - If the date in the title is only `DD.MM`, take the year from body / calendar / current session context. If the year is ambiguous — surface `Week ambiguity: date in <repo>#N is ambiguous; not writing GitHub until clarified` and halt the label write.

+ - If syncing in a different week from the event, show both: `event week: W22`, `sync week: W23`.

+ - If an existing dated issue has a stale or missing W-label, surface: `Week drift: <repo>#N «title» — has <labels>, should have W{NN}; action: add W{NN}`.

+

+ ### Week drift vs Project drift (read mode)

+

+ These are two independent conditions — an issue can have one without the other:

+

+ - **Week drift:** issue has a W-label that doesn't match the current calendar week for the work → `Week drift: issue has W{NN}, expected W{MM} by date; action: add W{MM}`

+ - **Project drift:** issue has the correct W-label but is absent from the expected Project board → `Project drift: W{NN} present, missing from <Project>; action: add to Project after W-label fix`

+

+ List both in the Track health section of read mode output.

+

+ ### Multi-week tasks

+

+ If a task requires action this week AND continues next week — apply BOTH W-labels. The index file is for "what's hot now"; labels record full lifecycle.

+

+ ### Backlog vs future-week

+

+ - If task is **deferred more than 1 week** without active work → `backlog` (create label if missing).

+ - If task is **planned for a specific future week** → `W{NN}` for that week.

+ - Never use `backlog` AND `W{NN}` together — pick one.

+

+ ### Creating / adding W-labels — fast-path

+

+ Do not call `gh label list` first to check existence. Immediately try to add it; only on failure create the label and retry:

+

+ ```bash

+ gh issue edit <N> -R "$REPO" --add-label "W{NN}" \

+ || { gh label create "W{NN}" -R "$REPO" --color "0E8A16" --description "Week {NN}"; \

+ gh issue edit <N> -R "$REPO" --add-label "W{NN}"; }

+

+ # backlog label

+ gh label create "backlog" -R "$REPO" --color "ededed" --description "Deferred — not on current/next week"

+ ```

+

+ Color `0E8A16` (dark green) for active weeks, `ededed` (neutral grey) for backlog. Old `retro:W*` and historical `W*` labels are never removed for tidiness.

+

+ ## Issue title convention

+

+ All new issues created by manager follow a fixed formula — canonical operational layer for agents (predictable parsing, search, groupBy).

+

+ ### Formula

+

+ ```

+ {object} — {action} ({when / context})

+ ```

+

+ Visible domain prefixes (`product:`, `content:`, `ops:`, `infra:`, `epic:`, etc.) are **NOT** written in the title. Type metadata lives in labels, the parent tree, Projects, and body.

+

+ | Segment | What | Examples |

+ |---------|------|----------|

+ | **`{object}`** | Recognizable subject first (noun) | `<track-A>`, `<product> L3`, `<person-name> S2`, `<handle>` |

+ | **`{action}`** | Verb + short scope | `prep for meeting <date>`, `process response + intake + slot` |

+ | **`{when / context}`** | Date/window/week in parens at end; optional | `(by <date>)`, `(<date> <time>)` |

+

+ ### Rules

+

+ 1. **No domain prefix in title.**

+ 2. **`{object}` is a noun first** for search ease (groups all of that track's tasks).

+ 3. **em-dash (—) separator** between object and action — visual anchor, easy to parse.

+ 4. **Date in parens at the end**, not the middle. Predictable placement.

+ 5. **No emojis in title** — clutter search and sorting.

+ 6. **Accept old prefixed titles as legacy aliases** in search/read. Do not auto-rename — only rename if user explicitly asked for bulk-rename.

+

+ ### Where type metadata actually lives

+

+ | Metadata | Location |

+ |----------|----------|

+ | Work type | labels (use your own taxonomy): `type:<work-type>`, `area:<domain>`, lifecycle labels |

+ | Track hierarchy | GitHub Sub-issues parent tree |

+ | Weekly visibility | W-label + Project placement |

+ | Owner / source | repo, Project, body fields |

+ | Root / epic status | sub-issues summary + body; no `epic:` prefix needed |

+

+ ### Product / runtime sub-patterns

+

+ | Situation | Pattern | Example |

+ |-----------|---------|---------|

+ | Bot / funnel / runtime feature | `<product or surface> — <fixed user behaviour> (<week/context>)` | `<bot handle> — duplicate request status without queue reset (W23)` |

+ | Ops discovery / runbook | `<system> — <operational capability or runbook>` | `<service> ops — one-off container commands via ssh (W23)` |

+

+ If a title is only understandable knowing a screenshot, a person's name, or a debugging-session history — the title is too situational. Details go in `## What was done`, `Evidence`, `Updates`; the title reflects the product outcome.

+

+ ### Examples

+

+ - `<track-A> — prep meeting <date> + budget by <date>`

+ - `<person-name> (<handle>) — process response + intake + slot`

+ - `<product> L3 — final prep for live (<date> <time>)`

+ - `<channel> — post recap <month> YYYY`

+

+ ### Anti-patterns

+

+ - ❌ `🔥 <track>: KP` — emoji + domain prefix

+ - ❌ `prep meeting on <date> for <track>` — verb-first instead of noun-first

+ - ❌ `ops: all about <event>` — domain prefix + too generic, no concrete action

+ - ❌ `partner: <track> → divergence ⚠️ overdue` — prefix, arrow instead of em-dash, emoji

+

+ ## Definition of done — body must be verifiable

+

+ When manager **creates** an issue or **reformats** an existing one, the body MUST contain verifiable completion criteria.

+

+ **Required minimum:**

+ 1. **Concrete scope checklist `- [ ]`** — what is specifically in scope, each item observable as done / not done.

+ 2. **Explicit "considered done when…"** — a closing condition tied to a verifiable artifact or observable behaviour.

+ 3. **Pointer to the source of scope** — where this scope came from: a skill section, a research report, a CRM slug, a parent epic, a meeting transcript.

+

+ **Vague one-liners without specifics are FORBIDDEN.** An issue body that cannot be verified against reality = malformed.

+

+ - ❌ `Implement rules from report X` — unclear which rules, which file, and when it's done.

+ - ✅ `- [ ]` checklist of concrete items + `done when rules are encoded in <skill>/SKILL.md § …` + link to source report.

+

+ If manager touches an existing vague issue (one-liner with no DoD), it adds the scope checklist + acceptance condition + source pointer in that same sync. Part of standard write sync under standing authorization.

+

+ ## Update vs create decision

+

+ **Default: update issue body, NOT add a comment.** Body = single source of truth, readable as one document. Comments stack chronologically and become unreadable after 5+ entries.

+

+ | Situation | Action |

+ |-----------|--------|

+ | Existing issue covers same scope, same track | **Edit body** — refresh "Status:", "Next:", and dated line in `## Updates`. Verify W-label is current AND parent epic attached AND Project placement present. |

+ | Existing issue scope is narrower but session expanded scope | Edit body of existing + create new follow-up issue with expanded scope, child of the same epic. |

+ | Multiple existing issues match different aspects (parent epic + sub-issue) | Edit body of the most specific child; touch epic only if its body needs updating. |

+ | No existing issue matches, but track is in tasks index | Create new issue. First resolve parent epic. W-label current, Project placement set. |

+ | No existing issue, no track in tasks index, fresh artifact | Ask user which repo + which epic before creating |

+ | Existing issue covers 2+ sibling scopes or belongs to a forecast/pipeline/operating review | Treat as aggregate issue. Find a repo-local aggregate epic first; if none, propose umbrella or split. |

+ | Existing child has a parent API link but appears flat in Project view | Do not reparent first. Verify parent Project placement + status lane; fix the parent Project item before changing hierarchy. |

+ | Found related issue with same subject but different scope | Keep as `Related` context only. Update/create a separate primary issue for the new standalone action. |

+

+ ### Comment is fallback, not default

+

+ Use a comment ONLY when:

+

+ - **Work-record after real session work on the issue** — one mandatory timeline comment per (session × issue): what was done + `refs`/SHA. This is the one case where a comment is required *in addition to* the body update (Iron invariant 6). One such comment per session per issue; don't stack — consolidate into body.

+ - The note is genuinely chronological and ephemeral (e.g. "blocked by external party until <date>") — would clutter body.

+ - User explicitly asked for a comment.

+

+ **Anti-pattern signal:** if you're about to write the third progress comment on an issue — that's two too many. Edit body instead.

+

+ ### Body update mechanics

+

+ Manager owns the read-modify-write pattern: `gh issue view` → local body file → `gh issue edit --body-file`, with refreshed `Status` / `Next` / `## Updates`. Use standard `gh` CLI directly.

+

+ ## Issue body template (when creating new)

+

+ Before writing any body to a **public** repo: replace private absolute paths, internal slugs, personal handles, payment facts, raw meeting/messaging URLs, and local-only evidence with safe public pointers. If no safe public pointer exists, record the private pointer only in the private/internal owner repo. Surface this as a blocker in the sync plan when applicable.

+

+ ```markdown

+ <one-line context: what changed/what was made>

+

+ **Source artifact:** <clickable GitHub URL — committed & pushed>

+ **Date:** <YYYY-MM-DD>

+ **Track:** <link to CRM card if commercial — see CRM integration>

+

+ ## What was done

+ <2-4 bullets — actual progress>

+

+ ## Scope

+ - [ ] <concrete item, observable as done/not-done>

+ - [ ] <concrete item>

+

+ ## Next step

+ <one line — what closes this issue (acceptance condition)>

+

+ ## Related

+

+ - <repo>#N «human-readable title» — brief reason for the link

+

+ **Verified:** <YYYY-MM-DD> by manager

+

+ Synced by manager from session <YYYY-MM-DD>.

+ ```

+ Add the `## Related` block **only when there are verified context links** — omit the whole block (don't leave it empty or with placeholder text) when there are none.

+ ## Body update template (default)

+ ```markdown

+ <one-line context: what changed/what was made — same as before, refresh if scope changed>

+ **Status:** <active / blocked / pending external / done — only "done" if user said so>

+ **Next:** <one-line next concrete step — refresh on each sync>

+ [... rest of original body content — REMOVE any old `## Related` block before re-writing ...]

+ ## Related

+ - <repo>#N «human-readable title» — brief reason for the link

+

+ **Verified:** <YYYY-MM-DD> by manager

+

+ ## Updates

+

+ - **YYYY-MM-DD:** <2-4 bullets of progress / decisions> (code: <repo>@<sha>)

+ - **YYYY-MM-DD:** <previous sync entry, kept>

+ ```

+

+ Remove any stale `## Related` block from the preserved original content, then insert at most one fresh verified block (omit when there are no real context links). Newest update at top of `## Updates`, oldest at bottom (pick once per issue and stay consistent).

+

+ ## Comment template (fallback only)

+

+ ```markdown

+ **YYYY-MM-DD:** <one-line note that doesn't fit body — e.g. "external blocker until X", "transient state observation">

+ ```

+

+ Work-record comment (the required case) lists what was done this session + `refs`/SHA. Keep comments short. If a comment grows beyond 4 lines — it belongs in body.

+

+ ## Output format

+

+ ### Issue reference format (CRITICAL)

+

+ **Always use `<repo>#N — «human title»` form when surfacing an issue to the user.** Bare `<repo>#27` is unreadable — the user needs the title to recognize the track at a glance.

+

+ - ❌ Bad: `<repo>#27 → comment + W19`

+ - ✅ Good: `<repo>#27 «<track-A> — respond to brief» → comment + W19`

+

+ ### Write mode — plan (BEFORE execution)

+

+ Compact plan. Each line: what I'll do + where + why. Group by track. Under each track, first line — **epic** (parent issue), then sub-issues with `parent: OK / parent: MISSING` marker. Decisions / ambiguities — inline as questions.

+

+ ```

+ Sync plan (W18, <date>):

+

+ <track-A> · epic crm#15 «<track-A> — B2B deal overview»

+ - crm#27 «<track-A> — respond to brief» [parent: crm#15 ✓; W18 ✓; Project ✓]

+ → body update + work-record comment; status → In progress

+ - crm#25 «<track-A> — prep meeting <date>» [parent: crm#15 ✓; W18 ✓; Project ⚠️ missing]

+ → comment "both meetings done"; add to Project; close if scope done, else keep open with reason

+

+ Labels to create: W19 in $YOUR_OWNER/crm

+ Epics missing coverage: (none)

+

+ Uncommitted in crm: meetings/<date>.md (new) — commit before sync?

+

+ Proceeding under standing authorization. If scope looks wrong — stop / correct.

+ ```

+

+ If a track has **no working epic**, surface separately:

+

+ ```

+ ⚠️ Epic missing: track «<X>» has no parent epic. Options:

+ - Create crm#NEW «<X> — overview» as umbrella; all 3 issues below become sub-issues.

+ OR

+ - Use existing <repo>#N «<title>» (sub_summary total=N) — ask if ambiguous.

+ ```

+

+ ### Write mode — report (AFTER execution)

+

+ ```

+ Done:

+ - crm#27 «<track-A> — respond to brief» — body update + work-record comment + W19; parent crm#15 ✓; Project → In progress

+ - crm#42 «<track-B> — scope expanded» — created, child crm#10, W18+W19, added to Project

+ - W19 label created in $YOUR_OWNER/crm

+

+ Skipped per your decision: crm#25 «<track-A> — prep…» — left open

+ ```

+

+ ### Read mode

+

+ Compact table — always with a «Title» column, parent epic in its own column, a Project column, no bare numbers:

+

+ ```

+ Query: «what about <track-A>»

+

+ Epic of the track: crm#15 «<track-A> — B2B deal overview» (3/5 done)

+

+ Open sub-issues:

+ | Issue | Title | Parent | W-label | Project | Activity | Status |

+ |-------|-------|--------|---------|---------|----------|--------|

+ | crm#27 | <track-A> — respond to brief | crm#15 ✓ | W18 ✓ | ✓ | <date> | Active — KP due <date> |

+ | crm#25 | <track-A> — prep <date> | crm#15 ✓ | W18 ✓ | ✓ | <date> | Both meetings done — likely stale |

+ | presentations#9 | <track-A> — deck audit | — ⚠️ | W18 ✓ | ⚠️ | <date> | No parent + missing from Project, attach to crm#15 |

+

+ In tasks index:

+ - 🔥 W18 priority 4 — «KP for <track-A> by <date>»

+

+ Not covered (gap):

+ - No issue for writing the KP itself (only prep). Create on next sync?

+

+ Track health check:

+ - 1 issue without parent epic — presentations#9. Attach on next sync.

+ - 1 issue missing from Project — presentations#9.

+

+ Drift in index / epic state:

+ - (optional) crm#15 epic — 5/5 sub-issues done, state OPEN. Candidate to close.

+

+ Filtered (false positives):

+ - crm#1 «<unrelated> — complete» — surfaced via W18 label, unrelated to <track-A>

+ ```

+

+ When a track has a multi-level epic hierarchy (root → lanes/children → grandchildren), output the read-mode report as a **tree, not a flat list**: each line carries parent status, W-label status, and Project placement. Active / current-week issues missing a Project slot are flagged `Project mismatch`.

+

+ ## Cross-references

+

+ - For weekly index management (when current week changes): see `weekly-planning` skill.

+ - For retro-driven backlog (when `retro:W*` labels appear): see `weekly-retro` skill — these labels carry historical signal, don't strip.

+

+ ## Common mistakes

+

+ | Mistake | Fix |

+ |---------|-----|

+ | Closing issues without explicit user instruction | Comment-and-leave-open is default. Only close if user said "close" or scope is fully delivered AND user mentioned completion. |

+ | Closing a delivery issue after local smoke only | A conducted live/session/workshop is not delivered until: recording/artifact ID or exact blocker recorded, the runtime/published artifact validated (not just locally), and the user-facing URL smoke check passes. Keep open with the exact open child otherwise. Don't infer enrollment/payment from view counts — verify against the authoritative source. |

+ | Removing legacy labels (`retro:W17`, etc.) for "tidiness" | Don't strip labels you didn't add. Append new W-label, leave legacy. |

+ | Picking single W-label for cross-week task | If a task spans current + next week, apply both. |

+ | Creating new issue when a comment in an existing one fits | Search broadly first (multiple keys / batched GraphQL). Only create if scope clearly diverges. |

+ | Skipping W-label create when missing in repo | Iron invariant — create the label (fast-path), don't skip. |

+ | Creating/touching an issue without a parent epic | Iron invariant — surface in proposal, don't be silent. |

+ | Treating W-label as sufficient | Need W-label + parent + Project placement (lane not empty). |

+ | Treating the API parent as sufficient | Verify the visible root Project item and its status lane. |

+ | Attaching one issue to two epics | GitHub supports one parent. Split into two issues, or treat as aggregate. |

+ | Markdown `Parent: #N` in body when API link exists | Duplicate, goes stale. Parent — only via Sub-issues API. |

+ | Missing SHA when commits exist | The `## Updates` entry must list short SHAs of session commits per touched repo. |

+ | Local `~/...` path as a deliverable link | Commit + push first; the body/report link is a clickable GitHub URL. |

+ | N×`gh issue view` one-by-one | Use batched GraphQL; single calls are a pointed fallback only. |

+ | Closing/syncing after real work without a work-record comment | Iron invariant 6 — add the timeline comment. |

+ | Not respecting the public-repo gate | Before writing to a public repo, do not add private / CRM / personal details; if unsure — surface in proposal and ask. |

+ | Treating tasks index as a general task list to mutate | The index is curated by user / `weekly-planning`; manager only patches rows for touched issues, closure cleanup, and explicit drift repair. |

+ | Acting on uncommitted local changes as "done" | Surface uncommitted work in the report; don't link a not-yet-pushed artifact. |

+ | Silently filtering false-positive matches | Drop from primary results but show in `IGNORED (false positives)`. |

+ | Treating every invocation as write mode | Check first: artifacts (write) OR question about state (read)? Use the mode resolution diagram. |

+ | Asking the user to open a URL/issue/file manually | Never. Bring the content back via `gh issue view <repo>/<N> --comments` yourself. |

+ | Bare issue numbers | Always `<repo>#N «title»`. Numbers are unrecognizable. |

+

+ ## Anti-patterns

+

+ - **Creating an issue without a parent epic** — breaks iron invariant. Surface in proposal, don't create orphan.

+ - **Creating new track-labels** — no longer done. Differentiation = title + epic membership.

+ - **Domain prefix in title** — superseded. Type metadata lives in labels/parent-tree/Projects.

+ - **Attaching one issue to two epics** — one parent per issue. Reconsider scope or treat as aggregate.

+ - **Markdown `Parent: #N` / `Epic: #N` in body when parent is set via API** — duplicate, goes stale.

+ - **Treating prose as Project-placement evidence** — use live `projectItems` reads, not "should be on the board".

+ - **Auto-closing stale issues** — never. Surface to user, leave open.

+ - **Broadly rewriting tasks index** — manager only patches rows for touched issues, closure cleanup, and explicit drift repair. Weekly structure belongs to `weekly-planning`.

+ - **Silent skip on tasks-index drift** — surface explicitly so the user can re-curate.

+ - **Silent skip on epic stale-open** — epic with 100% sub-issues done but `state = open` is a real signal; surface as candidate-to-close, never auto-close.

+ - **Single mega-comment dumping whole session** — one comment per issue, scoped to that issue's track.

+ - **Creating issues across repos for the same artifact** — one artifact = one primary issue.

+ - **Skipping search** — always search before create. Bias toward update.

+ - **Dumping full investigation output to chat** — readings are silent; only the proposal is visible.

+ - **Asking the user to re-list session artifacts** — infer from conversation context.

+ - **Bare issue numbers** — always `<repo>#N «title»`.

+ - **Skipping tasks index before gh search** — pre-flight is not optional.

+ - **Adding comments instead of updating body** — body is the main channel; comment only for work-record / genuinely ephemeral notes.

+

+ ## CRM integration (optional)

+

+ Activate by setting `crm_path` and `crm_pointer_format` in your `AGENTS.md` / `CLAUDE.md` config.

+

+ When CRM integration is enabled, every commercial / communication-related issue body must include a pointer to the corresponding CRM artifact (person card, opportunity card, meeting note). Default pointer format is `[[<slug>]]` (Obsidian wiki-link style), but you can configure any format your CRM uses.

+

+ For commercial / mentoring tracks, keep money out of the GitHub task body — price, package balance, paid/won status, and deal-close language live in CRM or the sales ledger. The issue body carries `[[<slug>]]` and a one-line pointer instead.

+

+ ```markdown

+ **Track:** [[<opportunity-slug>]]

+ ```

+

+ Manager checks the CRM path exists when activated; if it doesn't — surfaces a one-line warning and proceeds without the pointer requirement.

+

+ ## Key reminders (recency — duplicate the critical)

+

+ **Before any gh call:** read the tasks index → otherwise it's shotgun search.

+

+ **Every issue must carry:** W-label + parent (Sub-issues API) + Project placement (non-empty status lane).

+

+ **Write mode always:** `In progress` on touched active issues; work-record comment on real work; commit↔issue SHA linkage; body is the channel, comment is the audit trail.

+

+ **Title:** `{object} — {action} ({when})`, no domain prefix; type metadata lives in labels/parent/Projects.

+

+ **Standing auth:** follow your configured mode — `execute-after-plan` runs scoped writes after the plan without a separate "confirm"; `ask-each-time` (default) shows the plan, then asks. Either way, ask on genuine ambiguity / hard blocker.

+

+ **Output language follows the project.** Technical tokens (`<repo>#N`, `W18`, commands) stay as-is.