# Humand Product Workflow

Cursor rules and skills for the Humand product team — feature planning, sprint reporting, and cross-repo visibility without needing local clones.

### What You Can Do

| How | What | Example |
|-----|------|---------|
| **Skill** `/setup` | First-time setup wizard — verifies all prerequisites and connectivity | `/setup` |
| **Skill** `/sprint-report <team>` | Cross-repo sprint health → Notion page: Jira tickets + linked PRs, status, blockers | `/sprint-report rhino` |
| **Skill** `/feature-estimate-plan` | Feasibility assessment, complexity sizing, per-repo implementation plan → Notion page | *"Plan the new reactions feature for feed posts"* |
| **Skill** `/hu-team-staging-status` | Per-repo staging vs develop status → Notion page | `/hu-team-staging-status shark` |
| **Jira** via Atlassian MCP | Search, read, create, transition issues; add comments & worklogs | *"What's open in SQRN this sprint?"* |
| **Confluence** via Atlassian MCP | Search, read, create, update pages & comments | *"Find the onboarding spec in Confluence"* |
| **Notion** via Notion MCP | Create/update pages with skill output (reports, plans) | Automatic — skills publish to Notion |
| **GitHub** via `gh` CLI | PRs, branches, code search, file reads across all HumandDev repos | *"Show me open PRs in humand-web"* |

**17 squads on file** (`.cursor/teams.json`): coyote, cross, devops, dolphin, eagle, grizzly, jaguar, koala, octopus, owl, panda, puma, raccoon, rhino, shark, squid, zebra — plus 5 non-squad projects (CESP, CSBM, HU, ITSM, PMDR).

### Beyond the Basics

You're not limited to the commands above. Some ideas:

- **"Compare two features"** — describe both; I'll map affected repos side-by-side and flag overlap / conflicts so you can sequence sprints smarter.
- **"What changed since last release?"** — give me a date or tag; I'll pull merged PRs + Jira transitions across all repos into a changelog draft.
- **"Audit a Jira epic"** — paste an epic key; I'll check every child ticket for linked PRs, missing estimates, or stale status and surface gaps.
- **"Draft a Confluence spec"** — describe the feature; after planning I can push a structured spec page straight into your space.
- **"Translate a feature"** — after planning, I can scaffold the new i18n keys in `hu-translations` for all 18 locales.
- **"Estimate cross-team impact"** — name a shared component in `material-hu`; I'll find every consumer across web, backoffice, and mobile so you know who to loop in.

If it involves Jira, Confluence, GitHub, or reasoning about the Humand codebase — just ask. The worst that happens is I tell you I can't.

---

## Agent Rules

### Style

- Work style: telegraph; noun-phrases ok; drop grammar; min tokens.
- Before handoff: run full gate (lint/typecheck/tests/docs).

### Git

- **No implicit writes.** Never run git write operations on your own initiative — only when the user explicitly asks.
- Destructive ops (`reset --hard`, `push --force`, `clean`, `rebase`) require extra confirmation even when requested.
- Read commands (`status`, `log`, `diff`, `show`, `branch -l`, `gh` reads) are always allowed without asking.
- Features and changes must be done on a branch and submitted via PR to `main`.

### Critical Thinking

- Fix root cause (not band-aid).
- Conflicts: call out; pick safer path.
- Leave breadcrumb notes in thread.

## Prerequisites

- [GitHub CLI (`gh`)](https://cli.github.com/) — authenticated via `gh auth login`
- `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars — primary Jira access via REST API
- Atlassian MCP configured in Cursor — fallback for Jira, required for Confluence
- Notion MCP configured in Cursor (`https://mcp.notion.com/mcp`) — skill output destination

## Repositories

| Repo | GitHub | Role |
|------|--------|------|
| humand-main-api | `HumandDev/humand-main-api` | Backend API |
| material-hu | `HumandDev/material-hu` | Shared component library |
| humand-web | `HumandDev/humand-web` | Web application |
| humand-backoffice | `HumandDev/humand-backoffice` | Admin panel |
| humand-mobile | `HumandDev/humand-mobile` | Mobile app |
| hu-translations | `HumandDev/hu-translations` | i18n translation files |

## Jira Configuration

- **Instance**: humand.atlassian.net
- **Ticket URL pattern**: `https://humand.atlassian.net/browse/<KEY>`
- **Primary access**: REST API via `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars
- **Fallback**: Atlassian MCP (also used for Confluence operations)

## Shared Data

Common team and project information (team aliases, project keys, etc.) must be persisted in JSON files inside `.cursor/` and referenced by skills at runtime — never hardcoded in skill definitions. This keeps skills generic and lets the data be updated in one place.

| File | Committed | Purpose |
|------|-----------|---------|
| `teams.json` | Yes | Team aliases → Jira project key mapping |
| `repos.json` | Yes | Repo metadata: platform classification, branch model (release-date / semver / explicit), scan flags, heuristics for unknown repos. Consumed by `team-staging-status.py` and `generate-sprint-report.py`. |
| `sprint-report-context.json` | Yes | Domain knowledge for sprint reports: custom field IDs, status mappings, hierarchy/rollup rules, fields to request |

`teams.json` schema notes:
- `members` is the single source of truth for team rosters (github login, display name, confidence metadata).
- `members_github` is deprecated; do not add it in new edits.
- Never load full `teams.json` into agent context. Resolve/validate with `.cursor/scripts/get-team-config.py`.
- Confidence thresholds for inferred members:
  - `high`: `merged_prs_with_team_key_200 >= 30`
  - `medium`: `10..29`
  - `low`: `3..9`
  - `very_low`: `1..2`
  - `manual`: `0` (kept from existing data without PR signal in the 200-PR window)

When adding new shared data (e.g., sprint board IDs, Confluence space defaults, stakeholder lists), follow the same pattern: create a `.cursor/<name>.json` file, document it here, and have skills read it. If the data is sensitive or machine-specific, gitignore it and provide an `.example.json`.

## Reusable Scripts

When a skill contains a step that could be useful to other skills, extract it into a standalone script in `.cursor/scripts/`. Scripts should be self-contained (clear usage, input/output contracts, no hardcoded skill-specific logic) so any skill can call them.

| Script | Purpose |
|--------|---------|
| `process-sprint-data.py` | **Primary data pipeline.** Merges MCP JSON pages, performs parent/subtask rollup (assignees, dev info, platforms), outputs compact digest to stdout + processed tickets JSON. Detects subtasks needing backfill. |
| `get-team-config.py` | Resolve one team (key/alias/name) or validate `teams.json` without printing the full file. |
| `search-prs-for-keys.sh` | Batch-search PRs across all 6 repos for a set of Jira ticket keys. Searches title text + branch names (`head:` qualifier). |
| `generate-sprint-report.py` | Takes Jira tickets JSON + optional PR/review/branch data, categorizes tickets, outputs markdown/CSV/JSON report. Includes sprint elapsed %, auto-generated observations. |
| `fetch-jira-dev-info.sh` | Query Jira's dev-status REST API for linked PRs/branches per ticket. Requires `JIRA_EMAIL` + `JIRA_API_TOKEN`. |
| `fetch-jira-sprint-issues.sh` | **Primary Jira data source.** Fetch sprint issues via REST API. Requires `JIRA_EMAIL` + `JIRA_API_TOKEN`. |
| `run-sprint-report.py` | End-to-end wrapper: resolves team from `teams.json`, fetches live Jira data, searches GitHub PRs for tickets missing dev info, calls `generate-sprint-report.py`. Always queries live — never reads cached files. |

When adding a new script, follow the same pattern: put it in `.cursor/scripts/`, make it executable, document it here, and include usage/input/output in a header comment.

## Available Skills

All skills are invoked explicitly with `/name`.

| Skill | Description |
|-------|-------------|
| `/setup` | First-time setup wizard — verifies gh, Atlassian MCP, Notion MCP, repo access, teams config |
| `/sprint-report <team>` | Cross-repo sprint health report from Jira + GitHub → Notion page |
| `/feature-estimate-plan` | Feature refinement, per-repo effort assessment, implementation plan → Notion page |
| `/hu-team-staging-status` | Per-repo staging vs production vs develop status for a given team → Notion page |