github-elements-tracking

What this skill does

## IRON LAW: User Specifications Are Sacred

**THIS LAW IS ABSOLUTE AND ADMITS NO EXCEPTIONS.**

1. **Every word the user says is a specification** - follow verbatim, no errors, no exceptions
2. **Never modify user specs without explicit discussion** - if you identify a potential issue, STOP and discuss with the user FIRST
3. **Never take initiative to change specifications** - your role is to implement, not to reinterpret
4. **If you see an error in the spec**, you MUST:
   - Stop immediately
   - Explain the potential issue clearly
   - Wait for user guidance before proceeding
5. **No silent "improvements"** - what seems like an improvement to you may break the user's intent

**Violation of this law invalidates all work produced.**

## Background Agent Boundaries

When running as a background agent, you may ONLY write to:
- The project directory and its subdirectories
- The parent directory (for sub-git projects)
- ~/.claude (for plugin/settings fixes)
- /tmp

Do NOT write outside these locations.

---

## GHE_REPORTS Rule (MANDATORY)

**ALL agent reports MUST be posted to BOTH locations:**

1. **GitHub Issue Thread** - Full report text (NOT just a link!)
2. **GHE_REPORTS/** - Same full report text (FLAT structure, no subfolders!)

**Report naming:** `<TIMESTAMP>_<title or description>_(<AGENT>).md`
**Timestamp format:** `YYYYMMDDHHMMSSTimezone`

**Examples:**
- `20251206143000GMT+01_epic_15_wave_launched_(Athena).md`
- `20251206143022GMT+01_issue_42_dev_complete_(Hephaestus).md`
- `20251206150000GMT+01_issue_42_tests_passed_(Artemis).md`
- `20251206160000GMT+01_issue_42_review_complete_(Hera).md`

**ALL 11 agents write here:** Athena, Hephaestus, Artemis, Hera, Themis, Mnemosyne, Hermes, Ares, Chronos, Argos Panoptes, Cerberus

**REQUIREMENTS/** is SEPARATE - permanent design documents with legal validity, NEVER deleted.

**Deletion Policy:**
- GHE_REPORTS should be git-tracked - it constitutes the pulse of the GHE plugin
- DELETE ONLY when user EXPLICITLY orders deletion due to space constraints
- DO NOT delete during normal project cleanup or just because reports were archived to GitHub

---

## Project Settings

This skill respects settings in `.claude/ghe.local.md`. Run `/ghe:setup` to configure.

| Setting | Effect on This Skill |
|---------|---------------------|
| `enabled` | If false, skip all GitHub Elements operations |
| `enforcement_level` | strict/standard/lenient - affects rule strictness |
| `serena_sync` | If false, skip SERENA memory bank integration |
| `auto_worktree` | If true, auto-create git worktree on claim |
| `checkpoint_interval_minutes` | Reminder interval for checkpoints |
| `notification_level` | verbose/normal/quiet output |

**Defaults** (no settings file): enabled=true, enforcement=standard, serena_sync=true

---

## Related GHE Skills

For specific operations, GHE provides specialized skills:

| Skill | Purpose |
|-------|---------|
| **ghe-requirements** | Create, version, and link requirements files. Use when starting features. |
| **ghe-changelog** | Maintain version history with git-diff. Track code, requirements, and design changes. |
| **ghe-status** | Check thread status and context |
| **ghe-claim** | Claim a thread for work |
| **ghe-checkpoint** | Post progress checkpoints |
| **ghe-transition** | Request phase transitions |
| **ghe-report** | Generate status reports |

### Key Workflows

**Starting a New Feature:**
1. Use **ghe-requirements** to create REQ file
2. Link requirements to DEV issue
3. Use **ghe-claim** to claim the thread
4. Follow TDD workflow from DEV manager

**Tracking Changes:**
1. Use **ghe-changelog** after significant commits
2. Updates automatically track requirements and code changes

**Requirements-First Development:**
All DEV threads MUST link to a requirements file. The DEV manager (Hephaestus) enforces:
- Requirements breakdown into atomic changes
- TDD cycle for each atomic change (RED-GREEN-REFACTOR)
- Test coverage verification before transition

---

# GitHub Elements Tracking

GitHub Issues as **permanent memory** for AI agents. Survives compaction, enables collaboration, provides complete traceability.

**Integrated with SERENA MCP memory bank** for project-level context and large document storage beyond GitHub's limits.

---

## FUNDAMENTAL PRINCIPLES (READ FIRST)

These principles are non-negotiable. Violating them corrupts the entire workflow.

### 1. THE SACRED ORDER: One Branch, One Phase at a Time

Each branch goes through phases in strict circular order:

```
DEV ───► TEST ───► REVIEW ───► DEV ───► ... (until REVIEW passes)
         │           │
         │           └─► PASS? → merge to main
         │
    Bug fixes ONLY (no structural changes, no new tests)
```

**Critical Rules:**
- **ONE phase thread open at a time** per branch
- Opening TEST = closing DEV
- Opening REVIEW = closing TEST
- REVIEW fail → back to DEV (NEVER to TEST)
- REVIEW pass → merge to main

### 2. NEW BUG REPORT = NEW BRANCH (ALWAYS)

When a bug report is posted as a **new GitHub issue**:
- ALWAYS create a NEW branch with NEW DEV → TEST → REVIEW cycle
- NEVER merge it into an existing review thread, even if related
- Mixing issues violates the Sacred Order

**Exception**: Comments posted directly IN an existing thread are handled within that thread.

### 3. RESPONSIBILITY BOUNDARIES

| Agent | Handles Bug Reports? | Handles Test Writing? | Renders Verdicts? |
|-------|---------------------|----------------------|-------------------|
| **DEV** | NO (creates new branches for validated bugs) | YES | NO |
| **TEST** | NO (only runs existing tests) | NO | NO |
| **REVIEW** | YES (triages ALL bug reports) | NO | YES |

**REVIEW handles ALL bug reports and quality evaluation. TEST only runs existing tests.**

### 4. THE 3-STRIKE RULE FOR BUG REPORTS

When a bug report cannot be reproduced:
1. **Strike 1**: Politely ask for more details
2. **Strike 2**: Politely ask again with specific questions
3. **Strike 3**: Politely close as "cannot-reproduce"

**ALWAYS be polite**, even when closing. Thank the reporter for their effort.

### 5. EVERY CONTRIBUTION IS VALUED

- Never dismiss a contribution as "nitpick" or "pedantic"
- Verify everything, assume nothing
- If valid, thank the contributor regardless of size
- Reply respectfully even when rejecting

---

## Terminology

Understanding the relationship between GitHub entities and workflow concepts:

| Term | Definition |
|------|------------|
| **Issue** | A GitHub Issue - the container/ticket that holds all work history |
| **Thread** | A phase-specific issue. A "DEV thread" is an issue labeled `phase:dev` |
| **Comment** | A reply within an issue - holds checkpoints, decisions, work logs |
| **Element** | A comment containing Knowledge, Action, and/or Judgement facets |

**Key insight**: Every thread IS an issue. The terms describe the same GitHub entity from different perspectives:
- "Issue" emphasizes the GitHub container (the thing with a number like #201)
- "Thread" emphasizes the phase role (DEV, TEST, or REVIEW work)

**Example**: Issue #201 labeled `phase:dev` is the "DEV thread" for JWT authentication. When DEV completes, issue #201 closes and issue #202 (labeled `phase:test`) opens as the "TEST thread" for the same feature.

**One thread per phase**: Each phase (DEV, TEST, REVIEW) gets its own issue. When phase transitions occur, the old issue closes and a new issue opens with the new phase label.

### Thread Naming Convention

All thread titles MUST follow this standard format:

| Thread Type | Title Format | Example |
|-------------|--------------|---------|
| **DEV** | `[DEV] #ISSUE - Short Description` | `[DEV] #201 - JWT Authentication` |
| **TEST** | `[TEST] #ISSUE - Short Description` | `[TEST] #201 - JWT Authentication` |
| **REVIEW** | `[REVIEW] #ISSUE - Short Description` | `[REVIEW] #201 - JWT Authentication` |
| **DEV (iteration)** | `[DEV] #ISSUE - Description (Iteration N)` | `[DEV] #201 - JWT Auth (Iteration 2)` |

**Rule