Skill: Jira Comment Logging

Purpose

Standardized logging of agent actions, decisions, and handoffs via Jira comments for complete audit trail.

When to Use

• Any agent completes an action on a ticket
• Agent hands off work to another agent
• Decision is made (technical or business)
• Blocker identified or resolved
• Status update needed

MCP Tools Used

Tool	Purpose
Atlassian:addCommentToJiraIssue	Add comments
Atlassian:getJiraIssue	Read existing comments

Configuration

All values come from config/project.json:

{
  "cloudId": "{{jira.cloudId}}"
}

---

Comment Format Standards

Agent Comment Header

All agent comments must start with:

🤖 **[Agent Name] Agent**

Standard Sections

• Action: What was done
• Notes: Additional context
• Next: What happens next / who picks up

---

Comment Templates by Action Type

Action Completed

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Business Analyst Agent**

**Action:** Created acceptance criteria

**Details:**
- Added 4 acceptance criteria based on stakeholder requirements
- Identified 2 edge cases for review
- No blocking dependencies found

**Next:** Product Owner validation`
})

Agent Handoff

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Business Analyst Agent** → **Software Architect Agent**

**Handoff:** Technical review needed

**Context:**
- Story fully analyzed
- 4 acceptance criteria defined
- Stakeholder confirmed requirements

**Questions for Architect:**
1. Recommended authentication approach?
2. Any concerns with session handling?

**Attached:** Requirements analysis complete`
})

Decision Made

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Software Architect Agent**

**Decision Made:** Technical approach selected

**Decision:** Use JWT tokens for authentication

**Rationale:**
- Stateless, scales horizontally
- Industry standard
- Existing library support

**Alternatives Considered:**
- Session-based: Rejected (scaling concerns)
- OAuth only: Rejected (adds complexity for MVP)

**Impact:** Affects all auth-related stories`
})

Blocker Identified

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Senior Developer Agent**

**🚫 Blocker Identified**

**Issue:** Cannot proceed with email sending
**Reason:** SMTP configuration not available
**Blocked Since:** 2024-01-15

**Impact:**
- This story blocked
- Email verification story also affected

**Required Action:**
DevOps to provide SMTP credentials

**Escalated To:** Orchestrator for stakeholder notification`
})

Blocker Resolved

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **DevOps Engineer Agent**

**✅ Blocker Resolved**

**Issue:** SMTP configuration
**Resolution:** Credentials added to environment config
**Blocked Duration:** 2 days

**Verification:**
- Test email sent successfully
- All environments updated

**Next:** Development can resume`
})

Code Review Feedback

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Senior Developer Agent**

**Code Review Complete**

**PR:** #123
**Status:** Changes Requested

**Feedback:**
1. ⚠️ Add input validation for email field
2. ⚠️ Missing error handling for network failures
3. ✅ Good test coverage
4. ✅ Clean code structure

**Required Changes:** 2
**Next:** Junior Developer to address feedback`
})

QA Testing Result

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **QA Engineer Agent**

**Testing Complete**

**Environment:** Staging
**Test Cases:** 8 executed

**Results:**
- ✅ Passed: 7
- ❌ Failed: 1

**Failed Test:**
- TC-04: Password reset with expired link
- Expected: Error message
- Actual: Application error

**Bug Created:** PROJECT-67

**Verdict:** Cannot accept until bug fixed`
})

Stakeholder Escalation

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Orchestrator Agent**

**📋 Escalated to Stakeholder**

**Decision Required:** Scope clarification

**Question:**
Should password reset allow username OR email, or email only?

**Options:**
1. Email only (simpler, more secure)
2. Username or email (more user-friendly)

**Recommendation:** Option 1 (email only)

**Impact:** Affects acceptance criteria #2

**Awaiting:** Stakeholder decision
**Ticket:** Assigned to stakeholder`
})

Stakeholder Decision Logged

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Orchestrator Agent**

**✅ Stakeholder Decision Received**

**Question:** Password reset identifier
**Decision:** Email only (Option 1)
**Decided By:** {{STAKEHOLDER_NAME}}
**Date:** 2024-01-15

**Rationale:** Security preference over convenience for MVP

**Actions:**
- Updated acceptance criteria
- Logged in Decision Log (Confluence)
- Notified Business Analyst

**Story unblocked, proceeding with implementation.`
})

Sprint Assignment

Atlassian:addCommentToJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  commentBody: `🤖 **Orchestrator Agent** - Sprint Planning

**Assigned to Sprint 6**

**Sprint Goal:** Complete user authentication flow
**Capacity Check:** ✅ Within velocity

**Commitment:**
- Story points: 5
- Sprint total: 27/30 points

**Dependencies:** None blocking
**Ready to start:** Day 1 of sprint`
})

---

Reading Comments for Context

Get Issue with Comments

Atlassian:getJiraIssue({
  cloudId: "{{jira.cloudId}}",
  issueIdOrKey: "PROJECT-45",
  expand: "renderedFields,changelog"
})

---

Used By Agents

Agent	Primary Comment Types
All Agents	Action completed, handoffs
Orchestrator	Escalations, decisions, sprint assignments
Senior Developer	Code review, technical decisions
QA Engineer	Test results, bug references
DevOps Engineer	Blocker resolution, deployment notes

Best Practices

1. Always include Next action - Who picks up from here
2. Be specific - Include ticket numbers, PR links, dates
3. Use consistent formatting - Follow templates
4. Don't duplicate - Reference other tickets instead of copying
5. Keep it scannable - Use headers, bullets, checkboxes

Error Handling

Error	Cause	Resolution
400 Bad Request	Invalid markdown	Simplify formatting
403 Forbidden	No comment permission	Check project permissions
404 Not Found	Invalid issue key	Verify issue exists