Issues In Practice

Everything starts with an Issue. The guide covers Issue types and lifecycle. This page covers how to handle them.

Relationship Map

Issues bridge Direction and Work Items. They also feed back into Direction when they reveal a problem with the team’s scope:

Direction (guiderails)
    │
    ▼
Issues Backlog   ← captured from everywhere
    │                  user feedback, monitoring, stakeholders,
    │                  incidents, team ideas
    │
    ├── Resolved directly (answer question, fix config, close incident)
    │
    └── Promoted to Work Item
           │
           ▼
       Delivery → Production Feedback
                      │
                      ├── generates new Issues
                      └── refines Direction guiderails

The Issues backlog never stops growing. The skill is continuous triage, not clearing it to zero.

Default Path + Branching

Default — any incoming Issue:

Capture → Triage → Decide → Act (resolve or promote) → Close

Incident (production failure):

Capture → Triage → Fix immediately → Post-mortem →
  ├── Close (one-off)
  └── Promote to Problem (recurring pattern) → Feature or Study

Incidents skip the normal queue. Fix first, classify after.

Quick question:

Capture → Triage → Direct research → Answer → Close

No Work Item needed.

Problem with unknown root cause:

Capture → Triage → Study →
  ├── Root cause found → Feature or Story to fix
  └── Hypothesis killed → Close, document finding

Study is the tool for unknowns. Never commit to fixing a Problem whose root cause you do not understand.

Infeasible or out-of-scope Idea:

Capture → Triage → Out of scope → Close promptly

Do not let Ideas linger. Close decisively when they clearly do not fit.

Issue that refines Direction:

Capture → Triage → Direction signal → Escalate to Direction review

When the same Problem surfaces repeatedly, the guiderails may need adjustment.

Role Map

ActivityPrimarySupportsWhen
CaptureAnyone—Any time
Triage — classifyProduct OwnerSoftware EngineerDaily or on-demand
Triage — severityIncident ManagerSRE, Security EngineerOn receipt for incidents
Direct fixSoftware Engineer—When root cause is clear
Promote to Work ItemProduct OwnerEngineering LeadWhen Issue is worth investing in
CloseWhoever resolved itProduct OwnerAfter resolution
Post-mortemIncident ManagerWhole team24-48 hours after incident
Direction escalationProduct OwnerEngineering LeadPattern reveals guiderail problem

Technique Table

TechniqueUse WhenOutputSkill
Issue TriageAny incoming unplanned workClassified Issue with type, severity, owner, next stepissue-guide
Issue Control WorkflowFull lifecycle managementEvent-driven lifecycle: capture → triage → resolve → closeReferenced by issue-guide
Incident Post-MortemAfter a significant incidentBlameless analysis, 1-3 action items with ownersNot yet available
Pattern RecognitionSame Issue type recursProblem-to-Feature promotion, process improvementNot yet available

Procedure Table

ProcedureWhat It DoesWiki Link
Issue Triage (coming)Classify incoming issue, assess severity, assign owner, decide actionWiki — planned
Incident Post-Mortem (coming)Timeline reconstruction, root cause, action item trackingWiki — planned
Adopting Modern XPOnboarding a team to the methodologyplanning/procedures/adopting-modern-xp.md

Artifact Table

ArtifactProduced ByConsumed ByFormat
Issue CardIssue Guide session or manual captureBacklog, Work Item creationMarkdown: type, description, source, next step
Problem CardIssue Guide sessionFeature, StudyStructured: title, impact, area, suspected cause
Idea CardIssue Guide sessionFeatureStructured: current flow, desired flow, success measure
Question CardIssue Guide sessionResearch taskStructured: unknown, why it matters, where to look
Incident CardIssue Guide session or on-call toolPost-mortem, ProblemStructured: severity, timeline, services, status
Incident Post-Mortem ReportPost-mortem sessionAction item trackingTimeline, root cause, action items
Issues BacklogContinuousPrioritisation, Work ItemsList of open Issues not yet acted on

Skip Conditions

ActivitySkip When
Full Issue cardIssue is trivial. A one-line note is fine. Issues are freeform.
Formal triage meetingTeam is small (≤3). Conversation replaces formal triage.
Issue type classificationType is obvious to everyone. Do not debate when path is clear.
Post-mortemMinor incident with clear root cause and no recurrence risk.
Pattern recognitionIssues are one-off and unrelated.
Escalation to DirectionIssue clearly fits within existing guiderails.

Issues are freeform. If a one-line Issue captures what needs to happen, that is enough.

Comments

Comments on each page are welcomed and are visible here and under the discussions tab of the github repository.

View discussions on GitHub ↗