Comprehensive Rules for building, integrating, and maintaining an AI-augmented issue-tracking system with TypeScript/Node.js, Express, and Jira REST API.
Modern development teams are drowning in issues. Between customer reports, production incidents, and CI/CD failures, your team spends more time managing tickets than fixing them. The result? Critical bugs slip through, P0 incidents take hours to resolve, and your developers context-switch themselves into exhaustion.
Every development team faces the same bottlenecks:
Your current system treats all issues the same, forcing humans to do work that machines should handle automatically.
These rules transform Cursor into an AI-powered issue tracking development environment that handles the cognitive overhead for you. Instead of building another basic CRUD app, you're implementing predictive analytics, automated triage, and intelligent workflow management.
Key Capabilities:
// Typical manual issue handling
app.post('/issues', async (req, res) => {
const issue = await Issue.create(req.body)
// Hope someone notices and picks it up
res.json(issue)
})
// AI-powered issue creation with automatic triage
export async function createIssue(
ctx: RequestContext,
data: CreateIssueDto
): Promise<Issue> {
const issue = await issueRepo.create(data)
// AI predicts priority and assignee
const [priority, assignee] = await Promise.all([
mlService.predictPriority(issue),
mlService.suggestAssignee(issue)
])
// Auto-assign based on AI confidence
if (assignee.confidence > 0.8) {
await assignIssue(issue.id, assignee.userId)
}
// Trigger automated workflows
await publishDomainEvent('IssueCreated', issue)
return issue
}
Scenario 1: Production Incident Response When your monitoring detects a P0 issue, the system automatically:
Scenario 2: CI/CD Integration Pipeline failures automatically generate issues with:
Scenario 3: Intelligent Duplicate Prevention
// Semantic duplicate detection
const similarity = await calculateSimilarity(newIssue, existingIssues)
if (similarity > 0.85) {
return suggestMerge(newIssue, similarIssue)
}
Reduce Triage Time by 70% AI automatically prioritizes and assigns issues, eliminating daily triage meetings and reducing time-to-assignment from hours to minutes.
Eliminate Context Switching Every issue comes with complete context: related code changes, deployment history, and suggested solutions based on similar past issues.
Prevent Priority Inflation ML models cross-reference priority assignments against historical data, flagging anomalies and maintaining priority discipline.
Improve Resolution Speed Predictive assignee suggestions route issues to developers with relevant expertise, reducing back-and-forth and accelerating resolution.
Maintain Audit Trail Every code change, deployment, and incident automatically references issue IDs, creating complete traceability from problem to solution.
# Initialize your AI-powered issue tracking system
npm init
npm install express prisma @prisma/client zod bull redis
npm install --save-dev @types/node typescript ts-node jest
Copy the provided rules into your .cursorrules file. The rules automatically configure:
// Domain service example
export class IssueService {
async transitionIssue(id: UUID, to: IssueStatus): Promise<Issue> {
const issue = await this.issueRepo.findById(id)
if (!this.isValidTransition(issue.status, to)) {
throw new AppError('INVALID_TRANSITION', 400)
}
return await this.prisma.$transaction(async (tx) => {
const updated = await tx.issue.update({
where: { id },
data: { status: to, updatedAt: new Date() }
})
await this.auditService.logTransition(issue, to)
await this.eventBus.publish('IssueStatusChanged', updated)
return updated
})
}
}
The rules include patterns for integrating Python ML services:
Set up automated workflows:
Week 1: Automated issue creation and basic AI triage operational
Week 2: Full workflow automation and team adoption
Month 1: Predictive analytics and optimization
Ongoing: Continuous improvement through ML feedback loops
Unlike traditional issue tracking systems that simply store data, this implementation treats issues as first-class domain entities with intelligent behavior. The AI components learn from your team's patterns, improving suggestions and automation over time.
The architecture separates concerns cleanly: TypeScript handles business logic and API management, while Python services provide ML capabilities. This separation allows you to iterate on AI features without disrupting core functionality.
Most importantly, these rules enforce conventions that scale. As your team grows, the automated triage and assignment systems prevent the chaos that typically emerges with manual processes.
Ready to eliminate issue tracking overhead and let your team focus on building features instead of managing tickets? These Cursor Rules provide the blueprint for an AI-powered issue tracking system that actually enhances developer productivity.
You are an expert in TypeScript, Node.js, Express, PostgreSQL, Jira REST API, Python (for AI micro-services), Docker, AWS.
Key Principles
- Treat issue data as first-class domain entities; enforce strict typing and validation at boundaries.
- Automate wherever possible: predictive analytics for triage, bot-driven status updates, CI/CD-triggered ticket creation.
- Centralize truth: *one* authoritative backlog per environment; forbid parallel tracking silos.
- Keep workflows declarative and configurable (YAML/JSON). Never hard-code status names or transitions.
- Prioritize visibility: every code change, deployment, or incident must reference an Issue-ID.
- Prefer functional, side-effect-free business utilities; isolate I/O, persistence, and 3rd-party integrations.
- Enforce naming conventions: kebab-case directories, camelCase variables, PascalCase types & enums.
- Maintain security by default: OAuth2 + PKCE for external APIs, row-level RBAC in the DB, MFA for dashboards.
TypeScript
- Always compile with `"strict": true`; enable `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`.
- Use `interface` for public contracts, `type` for compositions/utility types.
- Mark DTOs with the suffix `Dto`; domain models with no suffix.
- Use `async/await`; never mix with `.then()` chains.
- Layered file layout:
/src
├── api # Express routes & controllers
├── domain # Pure TS business logic (no I/O)
├── integrations # Jira, Slack, Email, etc.
├── jobs # Cron & queue processors
├── prisma # DB schema & generated client
└── tests # Jest tests
- Limit functions to ≤ 40 LOC; extract helpers when cognitive complexity > 15.
- Prefer `enum IssueStatus { OPEN, TRIAGED, IN_PROGRESS, BLOCKED, DONE, CLOSED }` over string literals.
- Validate all external input with `zod`; convert to domain objects immediately.
Error Handling and Validation
- Guard clauses first; return early for invalid payloads, missing auth, or forbidden transitions.
- Use a single `AppError` class carrying `code: "BAD_REQUEST" | "NOT_FOUND" | ...` & `httpStatus`.
- Central Express error middleware logs (pino) ➜ APM (Datadog) ➜ returns sanitized message.
- Record errors as *Issue* entities when severity ≥ S2; auto-assign to on-call owner.
Express Framework Rules
- Route pattern: `POST /issues`, `PATCH /issues/:id/transition`, `GET /issues?status=OPEN`.
- Controllers are thin: validate ↔ call domain service ↔ map result ↔ send JSON.
- Use `express-async-errors` to bubble promises to error handler.
- Authenticate with JWT (internal) and OAuth2 (external); authorize via `can(user, action, resource)` helper.
- Pagination default: `limit=50`, `cursor` style; never offset for >10k rows.
AI & Automation Integration
- Isolate ML in a Python micro-service (FastAPI). TS service calls via gRPC.
- Prediction endpoints:
• `/predict/priority` → returns P0–P4 probability distribution.
• `/predict/assignee` → suggested userId.
- Cache ML results 10 min in Redis; invalidate on ticket update.
- Allow manual override; persist both AI suggestion and human choice for model retraining.
Database & Persistence (PostgreSQL via Prisma)
- Tables: `issues`, `comments`, `attachments`, `issue_events` (audit log).
- Use `uuid` primary keys; store Jira correlation in `external_id` (unique, nullable).
- Enforce FK `ON DELETE CASCADE` for comments/attachments.
- Soft-delete with `deleted_at`; never hard-delete rows referenced in history.
Testing
- Jest + ts-jest; coverage ≥ 90% on domain layer.
- Contract tests for integrations using Pact.
- Use `supertest` for API e2e; spin Dockerized Postgres 15 via `testcontainers`.
- Fixture naming: `issue_open.json`, `issue_triaged.json`.
Performance
- Index `issues(status, priority)` and `issues(updated_at DESC)`.
- Queue heavy operations (screenshot diff, ML scoring) in BullMQ; workers ≤ 75% CPU.
- Add `etag` header to GET /issues/:id; client caches for 5 min.
Security
- Sanitize HTML in descriptions with `DOMPurify.sanitize` on server.
- Store files in S3; use pre-signed URLs.
- Enable Field-Level Encryption for PII (`crypto-js` AES-256-GCM).
Observability
- Emit OpenTelemetry traces; traceId stored on each issue for RCA.
- Metrics: `issues_created_total`, `issues_resolution_seconds`, `ai_suggestion_accuracy`.
- Alerts: P0 open > 1 hr triggers PagerDuty.
Workflow & Naming Conventions
- Issue Title: `[<component>] <short imperative statement>` e.g., `[auth] cannot refresh token`.
- Template fields: `Steps to Reproduce`, `Expected`, `Actual`, `Logs`, `Customer Impact`, `Severity (S0–S4)`.
- Branch naming: `issue/<id>-<slug>` → `issue/1234-auth-token-expiry`.
- Commit message must start with `ISSUE-<id>: <summary>`.
CI/CD & Traceability
- Git hook rejects commits without valid Issue-ID.
- On failed pipeline stage, GitHub Action calls `POST /issues` (severity S2, label CI) auto-linked to run ID.
- Deploy script annotates release in Jira with fixVersion and closed issues list.
Documentation
- Host API contract in OpenAPI 3.1; auto-publish to portal.
- Maintain `CONTRIBUTING.md` with onboarding for issue workflow & labels.
- Weekly grooming script posts backlog stats to Slack channel #triage.
Common Pitfalls & How to Avoid
- **Stale tickets**: cron job marks issues idle > 14d as `STALE`; notifies assignee + lead.
- **Duplicate issues**: calculate trigram similarity on title + steps; suggest merge candidates.
- **Priority inflation**: ML model cross-checks P0/P1 counts; flags anomalies for PM review.
Example Code Snippet (Transition Service)
```ts
export async function transitionIssue(
ctx: RequestContext,
params: { id: UUID; to: IssueStatus }
): Promise<Issue> {
const issue = await issueRepo.findById(params.id)
if (!issue) throw new AppError('NOT_FOUND', 404)
if (!can(ctx.user, 'transition', issue)) throw new AppError('FORBIDDEN', 403)
if (!isValidTransition(issue.status, params.to)) {
throw new AppError('BAD_REQUEST', 400, `Invalid transition from ${issue.status} to ${params.to}`)
}
return await prisma.$transaction(async (tx) => {
const updated = await tx.issue.update({
where: { id: params.id },
data: { status: params.to, updatedAt: new Date() }
})
await tx.issueEvent.create({
data: {
issueId: params.id,
type: 'STATUS_CHANGED',
from: issue.status,
to: params.to,
actorId: ctx.user.id
}
})
publishDomainEvent('IssueStatusChanged', updated)
return updated
})
}
```
These rules provide a battle-tested foundation for building, scaling, and maintaining an AI-enabled issue-tracking ecosystem with robust code quality, security, and operational excellence.