From e0a9cc66feff13fe3a8d150d8bf977b014174a85 Mon Sep 17 00:00:00 2001 From: monthop-gmail Date: Tue, 17 Feb 2026 23:35:07 +0700 Subject: [PATCH] Add docs issue form and tighten triage SLAs --- .github/ISSUE_TEMPLATE/bug-report.yml | 55 ++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/docs-improvement.yml | 36 +++++++++++++ .github/ISSUE_TEMPLATE/governance-change.yml | 33 ++++++++++++ .github/ISSUE_TEMPLATE/issue_template.md | 15 ------ .github/ISSUE_TEMPLATE/question.yml | 28 ++++++++++ docs/issue-triage.md | 50 ++++++++++++++++++ docs/roadmap.md | 23 +++++++- 8 files changed, 229 insertions(+), 16 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/docs-improvement.yml create mode 100644 .github/ISSUE_TEMPLATE/governance-change.yml delete mode 100644 .github/ISSUE_TEMPLATE/issue_template.md create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 docs/issue-triage.md diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..5790f81 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,55 @@ +name: Bug report +about: Report a defect that is reproducible and impacts expected behavior +labels: [bug] +body: + - type: textarea + id: summary + attributes: + label: Problem summary + description: What happened vs what should happen? + placeholder: Actual behavior / Expected behavior + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Reproduction steps + description: Provide exact steps, inputs, and data needed to reproduce + placeholder: | + 1. ... + 2. ... + 3. ... + validations: + required: true + + - type: dropdown + id: plane + attributes: + label: Affected plane + options: + - Control Plane + - Orchestration Plane + - Execution Plane + - Observability Plane + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Suggested priority + description: Use triage matrix from docs/issue-triage.md + options: + - P0 + - P1 + - P2 + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Runtime, versions, deployment context + placeholder: OS / versions / branch / commit diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..564c411 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Contribution guide + url: https://github.com/monthop-gmail/devfactory-core/blob/main/CONTRIBUTING.md + about: Read contribution conventions before opening an issue. diff --git a/.github/ISSUE_TEMPLATE/docs-improvement.yml b/.github/ISSUE_TEMPLATE/docs-improvement.yml new file mode 100644 index 0000000..9d57fdf --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs-improvement.yml @@ -0,0 +1,36 @@ +name: Docs improvement +about: Suggest documentation fixes or improvements +labels: [docs] +body: + - type: textarea + id: problem + attributes: + label: Documentation problem + description: What is missing, unclear, or incorrect? + validations: + required: true + + - type: textarea + id: location + attributes: + label: Affected files/sections + description: List files or URLs if known + placeholder: docs/roadmap.md, README.md, ... + + - type: textarea + id: proposal + attributes: + label: Proposed improvement + description: What should be changed? + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Suggested priority + options: + - P1 + - P2 + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/governance-change.yml b/.github/ISSUE_TEMPLATE/governance-change.yml new file mode 100644 index 0000000..5a2f776 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/governance-change.yml @@ -0,0 +1,33 @@ +name: Governance or architecture change +about: Propose changes that affect policy, risk, approvals, or architecture direction +labels: [governance, architecture] +body: + - type: textarea + id: proposal + attributes: + label: Proposal + description: Describe the change and intended outcome + validations: + required: true + + - type: textarea + id: alignment + attributes: + label: Direction-lock alignment + description: Explain alignment with governance-first architecture and plane separation + validations: + required: true + + - type: textarea + id: risk + attributes: + label: Risk and approval impact + description: What risks are introduced? Any human-in-the-loop requirement changes? + validations: + required: true + + - type: input + id: rfc + attributes: + label: Related RFC (optional) + placeholder: rfcs/xxxx-*.md diff --git a/.github/ISSUE_TEMPLATE/issue_template.md b/.github/ISSUE_TEMPLATE/issue_template.md deleted file mode 100644 index 9bf2fff..0000000 --- a/.github/ISSUE_TEMPLATE/issue_template.md +++ /dev/null @@ -1,15 +0,0 @@ -# Issue Template - -## Problem Description - -## Alignment with Project Vision - -## Affected Plane -- [ ] Control Plane -- [ ] Orchestration -- [ ] Execution -- [ ] Observability - -## Risk Assessment - -## Expected Outcome diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..aa1d68c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,28 @@ +name: Question +about: Ask a scoped implementation or architecture question +labels: [question] +body: + - type: textarea + id: question + attributes: + label: Question + description: What do you need clarified? + validations: + required: true + + - type: textarea + id: context + attributes: + label: Context + description: Relevant files, docs, links, and constraints + + - type: dropdown + id: area + attributes: + label: Related area + options: + - Core State Machine + - Governance Engine + - Orchestration Foundation + - Observability + - Documentation / Process diff --git a/docs/issue-triage.md b/docs/issue-triage.md new file mode 100644 index 0000000..e054894 --- /dev/null +++ b/docs/issue-triage.md @@ -0,0 +1,50 @@ +# Issue Triage Guide + +This guide defines a lightweight process for handling incoming GitHub issues in `devfactory-core`. + +## 1) Intake +- Confirm the issue is reproducible. +- Collect: expected behavior, actual behavior, reproduction steps, and environment. +- Tag with one of: `bug`, `docs`, `architecture`, `governance`, `question`. +- Prefer structured issue forms in `.github/ISSUE_TEMPLATE/*.yml` to normalize inputs. +- Ensure labels are from the supported set: `bug`, `docs`, `architecture`, `governance`, `question`. + +### Intake from restricted environments +If GitHub API access is blocked (e.g., `403` from unauthenticated requests): +- Use the issue web URL and manually capture title/body/comments into triage notes. +- Request a token-backed mirror process in CI for `issues.json` export. +- Do not block triage; continue with reproducibility and alignment checks using available context. + +## 2) Alignment Check +Before implementation, verify alignment with project direction: +- Governance-first infrastructure +- Control/Orchestration/Execution/Observability plane separation +- Explicit state-machine workflows + +Reject or defer issues that push the project toward chatbot-only or SaaS-MVP scope. + +## 3) Prioritization +Use this simple matrix: +- **P0**: breaks architecture direction or blocks core state machine work +- **P1**: major feature gap within existing roadmap +- **P2**: quality/docs/ergonomics + +## 4) Resolution Checklist +- Add/update docs and architecture notes where behavior is defined. +- Reference related RFCs when introducing process or policy changes. +- Record follow-up tasks in `docs/roadmap.md`. + +## 5) Close Criteria +Close an issue only when all are true: +- Reproduction no longer fails (or docs clarify intentional behavior) +- Scope is aligned with project direction lock +- Linked commit/PR clearly documents the change + +## 6) Response targets +- **First response:** within 1 business day for P0/P1, 3 business days for P2. +- **Triage decision:** within 2 business days after first response. + +## 7) Weekly issue operations cadence +- **Daily:** 15-minute intake sweep and label hygiene. +- **Twice weekly:** prioritization review for P0/P1 items. +- **Weekly:** roadmap mapping check (every open issue must map to a phase, or be explicitly deferred). diff --git a/docs/roadmap.md b/docs/roadmap.md index fad5dcb..fc4bf83 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1 +1,22 @@ -Phase 1: Core State Machine +# Roadmap + +## Phase 1: Core State Machine +- Define canonical states for intake, plan, execute, review, and merge. +- Document transition guards and approval requirements. +- Produce an RFC for error and retry semantics. + +## Phase 2: Governance Engine +- Add policy model for risk classification and escalation. +- Define human-in-the-loop checkpoints and override paths. +- Specify immutable audit logging requirements. + +## Phase 3: Orchestration Foundation +- Document task decomposition and agent assignment strategy. +- Define retry and timeout policies per task type. +- Specify provider isolation and cost-control constraints. + +## Cross-cutting: Issue Operations +- Standardize issue triage with `docs/issue-triage.md`. +- Enforce structured issue forms and labels (`bug`, `docs`, `question`, `governance`, `architecture`). +- Use priority classes (P0/P1/P2). +- Ensure issues map to roadmap phases or direction-lock decisions.