traxxall-pbi-author

When to invoke

Invoke when the user asks to:

• "Draft a PBI" or "draft a Bug" for a new backlog item.
• "Create a PBI" (escalates to ADO only after confirmation + PAT check).
• Convert a finding, hotfix, or Zendesk ticket into a PBI.

---

Step 1: Load standards

Read skills/traxxall-standards/SKILL.md for:

• WI types in use (PBI, Bug, Task — no Epics/Features/User Stories).
• Area path (Traxxall Solution).
• Tags model (product tags + AI First).
• Sprint naming (YYYY-MM-DD Friday end date).
• Draft-vs-create discipline.
• Auth and egress mechanics.

---

Step 2: Gather required information

Collect the following before drafting. Prompt the user for any missing item:

Field	Source	Notes
Title	User input	Short, imperative, present-tense. E.g., "Fix N+1 query causing latency on Admin grid".
Type	User input	PBI or Bug.
Description	User input or intake brief	What is happening now vs what should happen. Plain text.
Acceptance criteria	traxxall-spec-author output or user input	Observable behaviour only — no class/method names.
Area path	Always Traxxall Solution	Fixed; never override.
Iteration (sprint)	User input or current date calculation	Current sprint = this week's Friday date; next sprint = next Friday date. Format: YYYY-MM-DD.
Product tag(s)	User input or triage result	At least one of: 360, Admin, Portal, Inventory/MMS, MRO, Scheduler.
AI tag	Always AI First for AI-authored items	Add AI Assist if human-authored with AI help.
Related WIs	User input or intake brief	Parent, related finding WI, Zendesk ADO link if hotfix.
Hotfix fields	User input (if HF)	Hotfix version, target branch, affected products.

If any required field is absent and cannot be derived, prompt for it. Do not fabricate iteration assignments or acceptance criteria.

---

Step 3: Draft mode (default)

Produce a paste-ready draft in this format:

## PBI Draft — {Title}

**Type**: PBI | Bug
**Title**: {title}
**Area Path**: Traxxall Solution
**Iteration**: {sprint-date}
**State**: New

**Tags**: AI First; {product-tag-1}; {product-tag-2 if applicable}

**Description**:
{2–4 sentences describing the problem or enhancement in plain, business-facing language. What is happening now. What should happen instead. No technical implementation detail.}

**Acceptance Criteria**:
{AC block from traxxall-spec-author, or authored here using Given/When/Then format.
Each AC: observable behaviour, input conditions, expected outcome.
No class names, method signatures, or internal concepts.}

**Related Work Items**:
- Parent: #{id} (if applicable)
- Related: #{id} — {title} (if applicable)
- Zendesk: {ticket URL} (if hotfix)

**Hotfix fields** (only for HF items):
- HF Version: {version}
- Target Branch: {releases/branch-name}
- Affected Products: {list}

State clearly at the top of the output: "This is a DRAFT. Review and paste into ADO manually, or confirm creation to proceed."

---

Step 4: Creation gate

Escalate to ADO creation ONLY when ALL of the following are true:

1. The user's message contains an explicit create instruction: "create it", "go ahead and create", "push to ADO", or equivalent.
2. traxxall-ado-auth confirms a Work-Items-write PAT scope is available.
3. All required fields (title, area path, iteration, at least one product tag, description, AC) are populated and non-empty.

When the gate passes, construct the az boards work-item create command:

az boards work-item create \
  --org https://dev.azure.com/{org} \
  --project "Traxxall Solution" \
  --type "Product Backlog Item" \
  --title "{title}" \
  --area "Traxxall Solution" \
  --iteration "Traxxall Solution\{sprint-date}" \
  --fields "System.Tags={tags}" \
  --description "{description}" \
  --output json

After creation, add related-WI links using:

az boards work-item relation add \
  --id {new-wi-id} \
  --relation-type "System.LinkTypes.Related" \
  --target-id {related-id} \
  --org https://dev.azure.com/{org}

Set acceptance criteria via REST PATCH (az boards does not support AC as a CLI flag):

# PATCH https://dev.azure.com/{org}/{project}/_apis/wit/workitems/{id}?api-version=7.1
# Body: [{"op":"add","path":"/fields/Microsoft.VSTS.Common.AcceptanceCriteria","value":"{AC-HTML}"}]

After creation succeeds, output the new WI URL and number.

---

Step 5: Validation before any create

Before issuing any az boards work-item create command, run this checklist:

• User explicitly said "create" (not just "draft" or "write up").
• traxxall-ado-auth PAT scope is Work-Items-write confirmed.
• Title is non-empty.
• Area path is exactly Traxxall Solution.
• Iteration is a valid future or current sprint date (YYYY-MM-DD).
• At least one product tag is set.
• AI First tag is set.
• Description is non-empty.
• Acceptance criteria are present and observable-behaviour-only.

If any check fails, block creation and state which check failed.

---

Output envelope (result shape)

{
  "wi_number": null,
  "wi_type": "PBI|Bug",
  "title": "Fix N+1 query causing latency on Admin grid",
  "area_path": "Traxxall Solution",
  "iteration": "2026-07-04",
  "tags": ["AI First", "Admin"],
  "ac_count": 3,
  "related_wi_ids": [16400],
  "hotfix": false,
  "hotfix_version": null,
  "created_in_ado": false,
  "ado_url": null
}

wi_number and ado_url are null in draft mode. They are populated only after confirmed ADO creation.