Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
18f71fc
feat(skills): add docs-handoff skill for post-delivery documentation …
redhat-chai-bot Nov 10, 2026
0dfb001
fix(docs-handoff): honest delivery semantics, PR identity validation,…
redhat-chai-bot Nov 10, 2026
6e3e5e4
fix(docs-handoff): real metadata catalog, digest verification, no pro…
redhat-chai-bot Nov 10, 2026
3fd6b0e
fix(docs-handoff): snapshot fingerprint, additive metadata payload, d…
redhat-chai-bot Nov 10, 2026
76ae35e
fix(docs-handoff): fresh snapshot drift detection, actual-field metad…
redhat-chai-bot Nov 10, 2026
9d8c0e1
fix(docs-handoff): source-context propagation and fail-closed metadat…
redhat-chai-bot Nov 10, 2026
95caa04
fix(docs-handoff): HTTPS-only PR URLs, fail-closed guards, and catalo…
redhat-chai-bot Nov 10, 2026
dbdbd3d
fix(docs-handoff): require explicit user approval before external writes
redhat-chai-bot Nov 10, 2026
0d633fd
fix(docs-handoff): schema accuracy for nullable target_branch and unc…
redhat-chai-bot Nov 10, 2026
bbbd4ec
fix(docs-handoff): remote_links validation, profile_fields casing, me…
redhat-chai-bot Nov 11, 2026
29e24a4
fix(docs-handoff): wire skipped_metadata into protocol references, ad…
redhat-chai-bot Nov 11, 2026
e408720
fix(docs-handoff): fence-aware sections, GitLab URL canon, target hon…
redhat-chai-bot Nov 14, 2026
43e8f65
fix(docs-handoff): fence-aware contributor extraction within section …
redhat-chai-bot Nov 14, 2026
5adcbfd
fix(docs-handoff): CommonMark-correct fence matching in section/contr…
redhat-chai-bot Nov 14, 2026
c283805
fix(docs-handoff): reject closing fences with info strings per Common…
redhat-chai-bot Nov 14, 2026
7dbfb16
fix(docs-handoff): CommonMark indentation and backtick-info fence rules
redhat-chai-bot Nov 14, 2026
f567e8b
fix(docs-handoff): handle tab indentation in fence boundary detection
redhat-chai-bot Nov 14, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -66,4 +66,5 @@ jobs:
- run: python3 -m unittest discover -s sizing/scripts -p 'test_*.py' -v
- run: python3 -m unittest discover -s triage/scripts -p 'test_*.py' -v
- run: python3 -m unittest discover -s skills/report-bug/scripts -p 'test_*.py' -v
- run: python3 -m unittest discover -s skills/docs-handoff/scripts -p 'test_*.py' -v
- run: python3 -m unittest discover -s design/scripts -p 'test_*.py' -v
7 changes: 6 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ This file provides guidance to AI coding assistants when working with this repos
This repository contains reusable AI coding workflows and focused skills that can be installed globally or per-project in any environment (Cursor, Claude Code, Gemini, Codex). Each package is a self-contained directory with structured markdown files that AI agents can read and execute.

**Current simple skills:**
- **docs-handoff** — Post-delivery documentation handoff for a single [DOCS] Jira issue with evidence gathering and enrichment
- **gh-stack** — Manages stacked PRs with gh-stack (creation, viewing, editing, push, submit, sync, rebase, merge, checkout)
- **report-bug** — Configurable, evidence-based Jira Bug reporting with explicit confirmation

Expand Down Expand Up @@ -272,6 +273,10 @@ ai-workflows/
├── triage/
├── ui-design/
├── skills/ # Focused skills (auto-discovered via SKILL.md)
│ ├── docs-handoff/
│ │ ├── SKILL.md
│ │ ├── references/
│ │ └── scripts/
│ ├── gh-stack/
│ │ ├── SKILL.md
│ │ └── references/
Expand All @@ -295,5 +300,5 @@ ai-workflows/
When a workflow or simple skill invokes commands that could affect shared systems:
- **Git operations**: Always verify with `git status` before destructive operations
- **PR/MR creation**: Confirm branch and base before pushing
- **Jira writes**: cve-fix `/close`, design `/sync`, ui-design `/sync`, sizing `/apply`, and `report-bug` may write to Jira; all require explicit approval. `report-bug` may create only the fully previewed issue and approved follow-up links/attachments
- **Jira writes**: cve-fix `/close`, design `/sync`, ui-design `/sync`, sizing `/apply`, `report-bug`, and `docs-handoff` may write to Jira; all require explicit approval. `report-bug` may create only the fully previewed issue and approved follow-up links/attachments. `docs-handoff` may add only approved PR Remote Links and eligible metadata to the target DOCS issue
- **Documentation changes**: Run Vale validation before applying changes to repository files
9 changes: 9 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ Reusable AI coding workflows and focused skills a team member can install global

### Skills

- **Docs Handoff** -- Post-delivery documentation handoff for a single `[DOCS]`
Jira issue. Gathers implementation evidence from contributing stories,
validates delivery, and produces a bounded enrichment plan with PR Remote
Links and an owning-source narrative proposal.
See [skills/docs-handoff/SKILL.md](skills/docs-handoff/SKILL.md).

- **gh-stack** -- Manages stacked PRs and splits multi-part work into reviewable
branches with `gh stack`. Covers creation, viewing, editing, push, submit,
sync, rebase, merge, and checkout.
Expand Down Expand Up @@ -88,6 +94,8 @@ supporting references or scripts they need. The installer discovers both forms.
docs-writer/
SKILL.md, skills/, commands/
skills/
docs-handoff/
SKILL.md, references/, scripts/
gh-stack/
SKILL.md, references/
report-bug/
Expand Down Expand Up @@ -212,6 +220,7 @@ Each workflow or skill is intended for a specific project or use case:
- **triage** -- teams that want bulk Jira triage, categorization, and HTML reports from this repo or a clone
- **sizing** -- teams sizing Features for cycle planning using T-shirt sizes with per-team effort breakdowns
- **skill-reviewer** -- reviewing or standardizing Cursor/agent skills and skill packs (structure, clarity, completeness)
- **docs-handoff** -- post-delivery documentation handoff for [DOCS] Jira issues with evidence gathering and PR Remote Link enrichment
- **gh-stack** -- managing stacked PRs with `gh stack` in any project using stacked branches
- **report-bug** -- filing complete Jira bugs with consumer-configurable targets and templates while leaving Priority for triage

Expand Down
28 changes: 28 additions & 0 deletions skills/docs-handoff/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
name: docs-handoff
version: 0.1.0
description: >-
Post-delivery documentation handoff for a single [DOCS] Jira issue. Gathers
implementation evidence from contributing stories, validates delivery, and
produces a bounded enrichment plan. Use after implementation PRs merge.
---

# Docs Handoff

Gather delivery evidence for one `[DOCS]` Jira issue and produce an
actionable handoff for the documentation writer.

1. Read [references/evidence-schema.md](references/evidence-schema.md)
for input validation, contributor extraction, and evidence contracts.
2. Read [references/jira-enrichment.md](references/jira-enrichment.md)
for the approved metadata and PR Remote Link write protocol.
3. Read [references/handoff-protocol.md](references/handoff-protocol.md)
for the preview/apply two-phase workflow and source-change proposals.

Inputs: one DOCS issue key, a selected release/target, and an optional
caller-supplied consumer profile. Outputs: delivery-evidence findings,
enrichment plan, and an owning-source narrative proposal when supported.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

**Boundaries:** No external write before the user explicitly approves
the exact bounded plan; stale or invalid requires fresh preview and
re-approval. Source/narrative apply is always disabled.
Comment thread
adalton marked this conversation as resolved.
Resolved
181 changes: 181 additions & 0 deletions skills/docs-handoff/references/evidence-schema.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
# Evidence Schema and Validation

Contract for DOCS issue validation, contributor extraction, and
delivery-evidence normalization used by `../scripts/evidence.py`.

## DOCS Issue Snapshot

The skill operates on a single `[DOCS]` Jira issue at a time. The
caller provides a JSON snapshot with at minimum:

| Field | Type | Required | Source |
|---|---|---|---|
| `key` | string | Yes | Jira issue key (e.g. `TEST-100`) |
| `summary` | string | Yes | Must contain `[DOCS]` prefix |
| `description` | string | Yes | Rendered Markdown from Jira |
| `status` | string | No | Current issue status |
| `parent` | object | No | Parent issue key and type |
| `remote_links` | array | No | Existing Remote Links |
| `issue_links` | array | No | Existing issue links |

The `validate` subcommand validates the snapshot and extracts structured
data. An offline snapshot file is fully supported — the skill does not
require live Jira access for validation.

## Required Description Sections

A valid `[DOCS]` issue description must contain these `##` sections:

- **Documentation Inputs** — planned user-facing artifacts grouped by
contributing story
- **Documentation Scope** — what the reader needs to understand
- **Acceptance Criteria** — reader-verifiable documentation outcomes

Missing sections produce validation errors. An empty Documentation
Inputs section (present but no parseable structured items) produces a
warning.

## Contributor Extraction

Contributors are extracted from the `Contributing stories:` line in the
Design Reference section. In a rendered (synced) issue, these are Jira
keys (e.g. `TEST-201`). Unresolved `Story N.NN` placeholders are
extracted as qualified IDs and flagged as warnings — they are gaps, not
fabricated live identities.

**Contributors vs Dependencies**: the `Dependencies` section lists
prerequisite stories. Dependencies are NOT automatically direct
contributors. The script extracts these separately. A contributor
that is *also* listed in Dependencies still requires evidence — the
dependency relationship does not exempt it from the contributor finding.

## Documentation Inputs Parsing

The Documentation Inputs section is parsed into structured items:

```text
**JIRA-KEY — title:**
- Input item text
- Another item [Assumption]
- Open item [Open: §9.2]
```

Each item records:
- `contributor`: the Jira key or qualified story ID from the header
- `text`: the original input description (markers preserved in text)
- `marker`: `planned` (default), `assumption`, or `open`
- `open_ref`: the referenced open question (when marker is `open`)

Missing or unparsed headers produce a visible warning, not a silent gap.

## PR Evidence Items

Each gathered PR evidence item must have:

| Field | Type | Required |
|---|---|---|
| `pr_url` | string | Yes — supported PR/MR URL (see URL validation) |
| `contributor_key` | string | Yes — Jira key of contributing story |
| `target_branch` | string/null | No — PR target branch (null normalized to empty) |
| `state` | string | No — PR state (open, merged, closed) |
| `title` | string | No — PR title |
| `merged` | boolean/null | No — whether PR is merged |
| `merge_commit` | string | No — merge commit SHA |
| `observations` | string[] | No — AI-generated semantic observations |

The `normalize` subcommand validates URLs (requiring supported PR/MR
structure with numeric ID), rejects embedded credentials, deduplicates
by normalized URL, detects contradictory `merged` or `target_branch`
values on duplicate PRs (surfaced as conflicts rather than silently
taking the first value), and preserves distinct repository identities.

Non-PR URLs, non-boolean `merged` values, and non-string observations
are rejected with errors.

## Input Status Values

After comparing planned inputs against gathered evidence, each input
receives a per-PR evidence status — not a blanket delivery claim:

- `merged_pr_exists` — contributor has a merged PR targeting the
expected branch
- `merged_wrong_target` — contributor has a merged PR but it targets a
different branch than expected
- `merged_unverified_target` — contributor has a merged PR but the
evidence target branch is unknown; merge to the expected branch cannot
be verified
- `in_progress` — contributor has PRs but none merged
- `no_evidence` — no PR evidence found for this contributor
- `evidence_unverified` — PRs exist but merge status is unknown (null)
- `conflicting` — contradictory evidence (e.g. merged=true and
merged=false on the same PR)

These are *observation* statuses. `merged_pr_exists` means a merged PR
exists — it does not prove the implementation matches the planned input
or that the feature is included in the target release. Semantic
assessment is an AI responsibility recorded in `observations`.

## URL Validation

PR/MR URLs must:
- Use HTTPS scheme (`validate_pr_url` rejects http; the generic
`validate_url` still accepts http for other URL types)
- Have no embedded credentials
- Match a supported forge pattern: GitHub `/owner/repo/pull/N` or
GitLab `/owner[/subgroup]*/repo/-/merge_requests/N`
- Have a numeric PR/MR identifier
- Be the canonical PR page (trailing paths like `/files` rejected)

Canonical normalization lowercases the scheme and host while
preserving path case, so `HTTPS://GITHUB.COM/Org/Repo/pull/1`
and `https://github.com/Org/Repo/pull/1` are the same identity.
Query strings and fragments are stripped for identity normalization.
Synthetic `.example`/`.invalid` domains are supported for testing.

## Current State Contract

The `check-enrichment` subcommand requires a `current_state` object:

| Field | Type | Required | Notes |
|---|---|---|---|
| `key` | string | Yes | Must match plan's issue key |
| `summary` | string | Yes | For snapshot drift detection |
| `description` | string | Yes | Raw description for drift detection |
| `remote_links` | array | Yes | Current Remote Links — each entry must be a dict with a string `url` |
| `fields` | object | No | Actual Jira field values |
| `fields.fixVersions` | array | Conditional | Required when plan proposes metadata; missing/null/non-list fails closed |
| `profile_fields` | object | No | Extra control metadata from consumer profile |

`remote_links` is validated before baseline computation: missing,
non-list, non-dict entries, or entries without a string `url` produce
an `invalid` result with zero eligible links and zero eligible
metadata. An explicit empty list (`[]`) is valid (known empty).

Unknown actual field values (missing `fields` or `fields.fixVersions`)
must NOT be fabricated as `[]` — they block metadata writes and appear
in `skipped_metadata` with the reason. An explicit empty list (`[]`)
is a known absence and permits writes. When the plan has no metadata
proposals, `fields` is not required (link-only flow).

## Check-Enrichment Output

The `check-enrichment` result contains:

| Field | Type | Notes |
|---|---|---|
| `status` | string | `ready`, `stale`, `invalid`, `invalid_plan`, `wrong_issue` |
| `eligible_links` | array | PR Remote Links approved for writing (empty when stale/invalid) |
| `existing_links` | array | Proposed links already present |
| `skipped_links` | array | Proposed links rejected with reason |
| `eligible_metadata` | object | Metadata fields approved for writing (empty when stale/invalid) |
| `skipped_metadata` | object | Metadata proposals not eligible — keyed by field name, each `{"reason": "...", "value": ...}` |
| `forbidden_fields` | array | Policy-blocked field names (distinct from skipped_metadata) |
| `baseline_fingerprint` | string | Approval token for Phase 2 |
| `plan_digest` | string | Approval token for Phase 2 |
| `stale` | boolean | Whether baseline or snapshot drifted |

`skipped_metadata` reports why each proposed metadata field could not
become an eligible write (e.g. `"not catalog_verified"`,
`"current_state.fields.fixVersions not present"`, `"must be a list"`).
`forbidden_fields` is separate — it captures policy-blocked fields
and uncatalogued entries, not conditional gaps.
Loading
Loading