From 8ff99f0766a232f9666baa94c8e85e2048169fc6 Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.nz>
Date: Tue, 15 Sep 2026 17:01:22 +0000
Subject: [PATCH] :books: Document how to add issues as sub-issues

Add the verified REST procedure for linking an issue as a
sub-issue of an umbrella/EPIC: get the REST id, POST to the
parent's sub_issues endpoint with a typed -F field, and verify
both directions. Route it from the create-issue skill.

AI-assisted-by: deepseek-v4.1-flash
---
 .agents/skills/create-issue/SKILL.md         |  3 ++
 .serena/memories/workflow/creating-issues.md | 41 ++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/.agents/skills/create-issue/SKILL.md b/.agents/skills/create-issue/SKILL.md
index 90a0fc3b75..8a4e5dde0f 100644
--- a/.agents/skills/create-issue/SKILL.md
+++ b/.agents/skills/create-issue/SKILL.md
@@ -19,6 +19,9 @@ right flow.
 - **Create from draft body** — Taiga story, user report, discussion; no PR
   yet.
   → memory section **Creating Issues from Draft Body**
+- **Create as sub-issue** — the issue must be grouped under an umbrella/EPIC
+  issue; create it first, then link it to its parent.
+  → memory section **Adding an Issue as a Sub-issue**
 - **Retitle existing issue** — current title is vague, prefixed, or stale.
   → memory section **Retitling an Existing Issue**
 
diff --git a/.serena/memories/workflow/creating-issues.md b/.serena/memories/workflow/creating-issues.md
index 54a2993fa8..f698c5031c 100644
--- a/.serena/memories/workflow/creating-issues.md
+++ b/.serena/memories/workflow/creating-issues.md
@@ -157,6 +157,47 @@ query { repository(owner: "penpot", name: "penpot") {
 rm -f /tmp/issue-body.md
 ```
 
+## Adding an Issue as a Sub-issue
+
+Sub-issues group work under an umbrella/EPIC issue. `gh issue create` cannot
+link a sub-issue at creation time: create the issue first (normal flow above),
+then link it.
+
+**1. Create the sub-issue** as usual and note its number (`NNNN`).
+
+**2. Get the issue's database id** (the REST `id`, not the `number`):
+
+```bash
+SUB_ID=$(gh api repos/penpot/penpot/issues/NNNN --jq .id)
+```
+
+**3. Link it to the parent** (`PARENT` = umbrella/EPIC issue number):
+
+```bash
+gh api --method POST repos/penpot/penpot/issues/PARENT/sub_issues \
+  -F sub_issue_id=$SUB_ID
+```
+
+Use `-F` (typed field), never `-f`: with `-f` the value is sent as a string
+and the API rejects it with `422 ... /sub_issue_id ... is not of type integer`.
+
+**4. Verify both directions:**
+
+```bash
+gh api repos/penpot/penpot/issues/NNNN/parent --jq '{number, title}'
+gh api repos/penpot/penpot/issues/PARENT/sub_issues --jq '.[] | {number, title}'
+```
+
+Notes:
+
+- The `POST` response is the parent issue and includes `sub_issues_summary`
+  with `total`, `completed` and `percent_completed`, useful to track EPIC
+  progress.
+- A sub-issue has a single parent.
+- Issue Type is independent of the parent relationship: choose it with the
+  normal mapping above (an EPIC child that fixes broken behavior is a Bug,
+  not a Task).
+
 ## Creating Issues from PRs
 
 Used when the project board needs an issue as the primary changelog/release