Ingest a GitHub issue into the principled documentation pipeline. Automatically determines what documents are needed and creates them pre-populated from the issue content.
-
Verify prerequisites. Check that gh is available and authenticated:
bash scripts/check-gh-cli.sh
If not available, report: "The gh CLI is required. Install it from https://cli.github.com/."
-
Fetch the issue. Extract issue metadata:
bash scripts/extract-issue-metadata.sh --number <issue-number>
Returns: title, body, labels, author, created date, comments, and state.
-
Check for existing principled documents. Search for an existing sync marker linking this issue to principled documents:
bash scripts/find-ingested-docs.sh --issue <issue-number>
If documents already exist, report them and ask if the user wants to update or create additional ones.
-
Normalize issue metadata. Before classifying, ensure the issue has well-structured metadata. Fix gaps directly on GitHub:
Title: If the issue title is vague, overly broad, or unclear (e.g., "fix thing", "it's broken", "update"), edit it to be descriptive:
gh issue edit <issue-number> --title "<improved-title>"
Component/scope labels: If the issue clearly affects specific modules or areas, add component labels. If urgency is evident, add priority labels:
gh issue edit <issue-number> --add-label "<labels>"
Do not add type labels (bug, enhancement, feature) in this step --- type classification happens in step 5 based on issue content analysis, and principled lifecycle labels are applied in step 10. Adding type labels here would create a feedback loop where step 5 classifies based on labels the agent just invented rather than human intent.
Body: If the issue body is empty or minimal but the title implies a concrete task, do not modify the body --- the created documents will provide the structure.
Report any metadata changes made to the user.
If --dry-run is set, report what changes would be made and stop. Do not proceed to step 5.
-
Classify the issue. Analyze the issue to determine what documents to create. Read reference/classification-guide.md for guidance. Classify based on issue content --- the body text and any pre-existing human-applied labels. Consider:
- Pre-existing issue labels —
bug, enhancement, feature, etc. (only labels that were present before step 4)
- Issue body length and complexity — longer, more detailed issues suggest larger scope
- Mentions of architecture, API changes, or cross-cutting concerns — suggest an RFC is needed
Classification outcomes:
- RFC + Plan: The issue describes something that needs design discussion and then implementation. Most features and significant changes fall here.
- Plan only: The issue describes well-scoped work where the approach is clear and doesn't need design review. Bug fixes with known root cause, small improvements with obvious implementation.
- Report the classification to the user and proceed.
-
Determine target directory. Based on arguments:
- If
--root: target is docs/ at the repo root
- If
--module <path>: target is <path>/docs/
- Otherwise: determine from current working context
-
Get the next sequence number(s). For each document type to create, determine the next available NNN in the target directory.
-
Create documents. For each document type:
If creating a proposal (RFC):
- Read
templates/ingested-proposal.md
- Populate frontmatter (title, number, status=draft, author from issue, dates)
- Map issue body sections into proposal sections (Context, Proposal, Open Questions)
- Add an ingest marker:
<!-- principled-ingested-from: #<issue-number> -->
- Write to
<target>/proposals/NNN-<slug>.md
If creating a plan:
- Read
templates/ingested-plan.md
- Populate frontmatter (title, number, status=active, originating_proposal if RFC was also created)
- Map issue body into plan sections (Objective, Tasks)
- Add an ingest marker:
<!-- principled-ingested-from: #<issue-number> -->
- Write to
<target>/plans/NNN-<slug>.md
-
Comment on the GitHub issue. Add a comment linking to the created documents:
gh issue comment <issue-number> --body "$(cat <<'EOF'
## Principled Pipeline
This issue has been ingested into the principled documentation pipeline:
- **RFC-NNN**: [`docs/proposals/NNN-slug.md`](link) — Status: draft
- **Plan-NNN**: [`docs/plans/NNN-slug.md`](link) — Status: active
Documents are the source of truth. Use `/sync-issues` to keep this issue updated.
<!-- principled-ingest-comment -->
EOF
)"
-
Apply labels. Add principled lifecycle labels to the issue based on what was created:
If RFC + Plan were created:
gh issue edit <issue-number> --add-label "type:rfc,proposal:draft"
If Plan only was created:
gh issue edit <issue-number> --add-label "type:plan,plan:active"
-
Report results. Summarize what was created:
- Document paths and types
- Issue comment link
- Labels applied
- Metadata changes made (title, labels added during normalization)
- Next steps: review and flesh out the generated documents
