Repository navigation
feat: add post-delivery DOCS handoff skill #162
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
redhat-chai-bot
wants to merge
17
commits into
flightctl:main
Choose a base branch
from
redhat-chai-bot:feat/docs-handoff
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
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 0dfb001
fix(docs-handoff): honest delivery semantics, PR identity validation,…
redhat-chai-bot 6e3e5e4
fix(docs-handoff): real metadata catalog, digest verification, no pro…
redhat-chai-bot 3fd6b0e
fix(docs-handoff): snapshot fingerprint, additive metadata payload, d…
redhat-chai-bot 76ae35e
fix(docs-handoff): fresh snapshot drift detection, actual-field metad…
redhat-chai-bot 9d8c0e1
fix(docs-handoff): source-context propagation and fail-closed metadat…
redhat-chai-bot 95caa04
fix(docs-handoff): HTTPS-only PR URLs, fail-closed guards, and catalo…
redhat-chai-bot dbdbd3d
fix(docs-handoff): require explicit user approval before external writes
redhat-chai-bot 0d633fd
fix(docs-handoff): schema accuracy for nullable target_branch and unc…
redhat-chai-bot bbbd4ec
fix(docs-handoff): remote_links validation, profile_fields casing, me…
redhat-chai-bot 29e24a4
fix(docs-handoff): wire skipped_metadata into protocol references, ad…
redhat-chai-bot e408720
fix(docs-handoff): fence-aware sections, GitLab URL canon, target hon…
redhat-chai-bot 43e8f65
fix(docs-handoff): fence-aware contributor extraction within section …
redhat-chai-bot 5adcbfd
fix(docs-handoff): CommonMark-correct fence matching in section/contr…
redhat-chai-bot c283805
fix(docs-handoff): reject closing fences with info strings per Common…
redhat-chai-bot 7dbfb16
fix(docs-handoff): CommonMark indentation and backtick-info fence rules
redhat-chai-bot f567e8b
fix(docs-handoff): handle tab indentation in fence boundary detection
redhat-chai-bot File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
|
|
||
| **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. | ||
|
adalton marked this conversation as resolved.
Resolved
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.