From cnf-doc-sync
Sync documentation changes from the private vz-cnf-best-practices-guide repo to the public Red Hat K8s guide repo. Use when the user wants to compare commits between private and public CNF/K8s guide repos, classify changes as Verizon-specific vs generic, generate a sync review report, launch the review UI, or create a PR from a reviewed report. Trigger on: doc sync, CNF sync, VZ guide sync, guide repo comparison, private-to-public sync, cnf-doc-sync, or any mention of syncing vz-cnf-best-practices-guide with guide.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cnf-doc-sync:cnf-doc-syncThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Synchronize documentation changes from the private Verizon CNF best practices repo to the public Red Hat K8s best practices repo. Changes are classified using AI content analysis, presented in a reviewable markdown report, and optionally turned into a PR on the public repo.
Synchronize documentation changes from the private Verizon CNF best practices repo to the public Red Hat K8s best practices repo. Changes are classified using AI content analysis, presented in a reviewable markdown report, and optionally turned into a PR on the public repo.
| Repo | Local Path | File Prefix | Role |
|---|---|---|---|
vz-cnf-best-practices-guide | /Users/bmandal/work/ai/vz-cnf-best-practices-guide | cnf-best-practices-* | Private (source) |
guide | /Users/bmandal/work/ai/guide | k8s-best-practices-* | Public (target) |
Verizon-specific modules use the cnf-best-practices-vz-* naming pattern. Shared modules map by topic: cnf-best-practices-<topic>.adoc in private corresponds to k8s-best-practices-<topic>.adoc in public.
/cnf-doc-sync <private-commit-hash> [public-commit-hash]
private-commit-hash (required): Commit in the private repo. Diff is from this commit to HEAD.public-commit-hash (optional): Commit in the public repo. Used as context — read public files at this commit to check if a change already exists./cnf-doc-sync --review <path-to-json-data>
Launches the web-based review UI for a previously generated JSON data file. Opens a browser for interactive accept/reject/edit decisions and PR creation.
/cnf-doc-sync --create-pr <path-to-reviewed-report.md>
Parses the reviewed markdown report and creates a PR on the public repo with accepted changes.
Parse the args string to determine the mode:
--review, extract the JSON data path after it. Enter Mode 2.--create-pr, extract the report path after it. Enter Mode 3.private-commit-hash (required). The second argument, if present, is the public-commit-hash (optional). Enter Mode 1.If no args are provided, tell the user the usage and stop.
Run these commands in the private repo (/Users/bmandal/work/ai/vz-cnf-best-practices-guide):
Validate the commit hash exists:
git -C /Users/bmandal/work/ai/vz-cnf-best-practices-guide cat-file -t <private-commit-hash>
If this fails, tell the user: "Commit <hash> not found in vz-cnf-best-practices-guide. Please provide a valid commit hash." and stop.
Get the list of changed files:
git -C /Users/bmandal/work/ai/vz-cnf-best-practices-guide diff <private-commit>..HEAD --name-status
Get the full diff content:
git -C /Users/bmandal/work/ai/vz-cnf-best-practices-guide diff <private-commit>..HEAD
If a public-commit-hash was provided, validate it in the public repo:
git -C /Users/bmandal/work/ai/guide cat-file -t <public-commit-hash>
If this fails, tell the user: "Commit <hash> not found in guide repo. Please provide a valid commit hash or omit it." and stop.
If no files changed, tell the user: "No changes detected between <commit> and HEAD." and stop.
Parse the diff output. Group changes by file. For each file, extract individual diff hunks (sections starting with @@).
Classify each changed file into an initial bucket by filename pattern:
Verizon-only: Files matching *-vz-* (e.g., cnf-best-practices-vz-networking-overview.adoc). These are auto-classified — skip AI analysis. They go directly into the "Verizon-Specific Changes" section of the report.
Shared: Files that have a matching counterpart in the public repo. To check, strip the cnf-best-practices- prefix from the private filename and look for k8s-best-practices-<same-topic>.adoc in /Users/bmandal/work/ai/guide/modules/. Run:
ls /Users/bmandal/work/ai/guide/modules/k8s-best-practices-<topic>.adoc
If the file exists, classify as Shared. These need AI content analysis.
Ambiguous: Non-VZ files with no matching public counterpart. These also need AI content analysis.
Also classify non-module files:
main.adoc changes: Classify as Shared (both repos have a main.adoc)..github/, scripts/, images/, README.md, CLAUDE.md, AGENTS.md: Classify as Verizon-only unless the change is clearly generic infrastructure. Use judgment.Count the files in each bucket for the report summary.
For each file classified as Shared or Ambiguous, dispatch a parallel Agent subagent to analyze the diff hunks. Use one Agent per file. Dispatch all agents in a single message for parallel execution.
If a public-commit-hash was provided and a matching public file exists, read the public file content at that commit:
git -C /Users/bmandal/work/ai/guide show <public-commit>:modules/k8s-best-practices-<topic>.adoc
Agent prompt template (substitute the actual values for each file):
You are analyzing a diff from a private Verizon CNF documentation repo to determine if the content is safe to sync to a public Red Hat Kubernetes best practices repo.
File:
**Current public file content (for reference):** ``` ```<FILENAME>Classification so far:<SHARED or AMBIGUOUS>Diff hunks to classify:
<PASTE ALL HUNKS FOR THIS FILE>Verizon-Specific Markers — classify as VZ-specific if ANY of these appear:
- "Verizon", "VCP", "Verizon Communications", "Verizon VCP"
- "Doors Id" or "Doors ID" (Verizon requirements tracking IDs)
- ".VCP CNF requirement" or ".VCP CNF recommendation" (admonition labels)
- "ENSE" (Verizon network fabric)
- "SPK" when used in context of Verizon-specific ingress/egress/load balancing
- Internal hostnames, URLs, or IP ranges
- References to "core ENSE", "edge ENSE" network fabric
- VZ core/edge compute specs (specific hardware references)
- Internal approval processes or Verizon organizational references
- VZ-specific container naming/labeling standards
- References to "CPI 810" or similar Verizon-internal standards
For EACH hunk, classify as one of:
- generic: Cloud-native best practice. No VZ markers. Safe for public.
- verizon-specific: Contains one or more VZ markers. Must stay private.
- mixed: Contains BOTH generic content AND VZ-specific content interleaved in the same hunk.
Respond with a JSON array, one entry per hunk:
[ { "hunk_number": 1, "classification": "generic|verizon-specific|mixed", "reason": "One sentence explaining why", "vz_references": ["list of VZ markers found, empty if generic"], "generic_summary": "Brief description of the generic content (if any)", "vz_summary": "Brief description of the VZ-specific content (if any)" } ]
Wait for all agents to complete. Parse the JSON responses.
If an agent fails or returns unparseable output, classify that file's hunks as mixed (safest default — forces manual review).
Aggregate results:
Write the report to cnf-doc-sync-report-<YYYY-MM-DD>.md in the current working directory. Use today's date.
Use this exact structure:
# CNF Doc Sync Report
**Date:** <YYYY-MM-DD>
**Private repo:** vz-cnf-best-practices-guide @ `<private-commit-short>`..`HEAD`
**Public repo:** guide @ `<public-commit-short>` (context) — or "N/A" if not provided
## Summary
- Total files changed: <N>
- Verizon-only (auto-classified): <N>
- Public-eligible: <N>
- Mixed (needs manual review): <N>
---
## Verizon-Specific Changes
Changes that should stay in the private repo only.
<!-- For each VZ-only auto-classified file: -->
### [AUTO] `<filename>`
> Auto-classified: VZ-prefixed file
<details>
<summary>Diff</summary>
\```diff
<paste the diff for this file>
\```
</details>
<!-- For each AI-classified VZ-specific hunk: -->
### [AI] `<filename>` — Hunk <N>
> Contains VZ-specific references: <reason from agent>
\```diff
<paste the diff hunk>
\```
---
## Public-Eligible Changes
Changes that can be synced to the public guide repo.
<!-- For each public-eligible file/hunk: -->
### [AI] `<filename>`
> <classification reason from agent>
> **Public counterpart:** `k8s-best-practices-<topic>.adoc` — or "No matching file in public repo" for Ambiguous files
- [ ] Accept
- [ ] Reject
- **Reviewer Notes:** _<add comments or modified content here>_
\```diff
<paste the diff>
\```
---
## Mixed Changes (Manual Review Required)
Hunks containing both generic and VZ-specific content.
<!-- For each mixed hunk: -->
### `<filename>` — Hunk <N>
> **Generic portion:** <generic_summary from agent>
> **VZ-specific portion:** <vz_summary from agent>
- [ ] Accept generic portion only
- [ ] Accept with modifications
- [ ] Skip entirely
- **Reviewer Notes:** _<add comments here>_
- **Modified Content (if accepting with modifications):**
\```text
<reviewer pastes rewritten content for public repo here>
\```
\```diff
<paste full diff hunk>
\```
---
## Actions
When your review is complete, invoke the skill with the report path:
\```
/cnf-doc-sync --create-pr cnf-doc-sync-report-<YYYY-MM-DD>.md
\```
This will:
1. Parse your Accept/Reject decisions and reviewer notes
2. Create a branch `sync/vz-<YYYY-MM-DD>` on the public guide repo
3. Apply accepted changes (using modified content where provided)
4. Create a PR with a summary of all included changes
After writing the markdown report, also generate a JSON data file at cnf-doc-sync-data-<YYYY-MM-DD>.json for the review UI. Use this structure:
{
"version": 1,
"created_at": "<ISO-8601 timestamp>",
"private_repo": "/Users/bmandal/work/ai/vz-cnf-best-practices-guide",
"public_repo": "/Users/bmandal/work/ai/guide",
"since_ref": "<private-commit-short>",
"head_ref": "<HEAD-short>",
"public_ref": "<public-commit-short or empty>",
"files": [
{
"id": "<unique-id, e.g. f1>",
"private_path": "<filename in private repo>",
"public_path": "<mapped k8s-best-practices-*.adoc filename, or empty>",
"file_classification": "vz_specific|shared|ambiguous",
"file_classification_reason": "<reason>",
"private_content_before": "<full file content before changes>",
"private_content_after": "<full file content after changes>",
"proposed_public_content": "<AI-sanitized content for public file, empty for VZ files>",
"final_content": "",
"decision": "pending|auto_excluded",
"reviewer_classification": "",
"hunks": [
{
"id": "<unique-id, e.g. f1-h1>",
"hunk_header": "<@@ line>",
"diff_text": "<raw diff text for this hunk>",
"classification": "generic|verizon-specific|mixed",
"reason": "<AI rationale>",
"vz_references": ["<VZ markers found>"],
"generic_summary": "<brief description of generic content>",
"vz_summary": "<brief description of VZ content>"
}
]
}
]
}
File content fields: For each file, read the full content before and after:
private_content_before: git -C <private-repo> show <since-commit>:<filepath> (empty string for new files)private_content_after: git -C <private-repo> show HEAD:<filepath> (empty string for deleted files)proposed_public_content: For files with generic hunks, generate the proposed public file content by taking the private_content_after and removing all VZ-specific content (VZ admonitions, Doors IDs, VZ-specific paragraphs). Replace cnf-best-practices- with k8s-best-practices- in any IDs or cross-references. Leave this empty for vz_specific files.
decision: Set to "auto_excluded" for vz_specific files, "pending" for all others.
After writing both files, tell the user:
"Report generated at <markdown-path>.
JSON data generated at <json-path>.
To review changes in the web UI, run:
/cnf-doc-sync --review <json-path>
Or review the markdown report and run:
/cnf-doc-sync --create-pr <markdown-path>"
When invoked with --review <json-path>:
.claude-plugin/marketplace.json, cnf_doc_sync_ui/, and frontend/. Typically this is at /Users/bmandal/work/ai/cnf-doc-sync-tool/ or wherever the user cloned the repo.cd <repo-root> && source .venv/bin/activate && python -m cnf_doc_sync_ui --data <json-path>
Prerequisites: The review UI must be set up first. If the .venv directory doesn't exist in the repo root, tell the user to run the setup script:
cd <repo-root> && ./setup.sh
When invoked with --create-pr <report-path>:
Read the report file at <report-path>. Parse it to extract:
Accepted Public-Eligible changes: Sections under "Public-Eligible Changes" where [x] Accept is checked. Extract:
cnf-best-practices-helm.adoc)**Reviewer Notes:** that is not the placeholder _<add comments or modified content here>_)Accepted Mixed changes: Sections under "Mixed Changes" where either [x] Accept generic portion only or [x] Accept with modifications is checked. Extract:
Skipped/Rejected: Ignore sections where [x] Reject, [x] Skip entirely, or no checkbox is checked.
If no changes are accepted, tell the user: "No changes were accepted in the report. No PR will be created." and stop.
git -C /Users/bmandal/work/ai/guide status --porcelain
If there are uncommitted changes, warn the user: "The public guide repo has uncommitted changes. Please commit or stash them before proceeding." and stop.
git -C /Users/bmandal/work/ai/guide checkout main
git -C /Users/bmandal/work/ai/guide pull origin main
git -C /Users/bmandal/work/ai/guide checkout -b sync/vz-<YYYY-MM-DD>
Use today's date. If the branch already exists, append a counter: sync/vz-<YYYY-MM-DD>-2.
For each accepted change:
Identify the target file. The report shows the private repo filename (e.g., modules/cnf-best-practices-helm.adoc). Look up the corresponding public file:
cnf-best-practices- prefix → helm.adocmodules/k8s-best-practices-helm.adoccnf-best-practices-helm.adoc → k8s-best-practices-helm.adoc"If "Accept with modifications" — the reviewer provided rewritten content in the "Modified Content" block. Read the current public file, find the location where the change applies (use surrounding context from the diff), and apply the reviewer's modified content using the Edit tool.
If plain "Accept" — the reviewer accepted the original diff. Read the current public file, apply the diff changes using the Edit tool. The diff is from the private repo so content references like IDs and cross-references may need to match the public repo's conventions — flag any cnf-best-practices references in the applied content and warn the user.
If the target public file does not exist (Ambiguous file with no counterpart), tell the user: "File <filename> has no counterpart in the public repo. Skipping — manual creation required." and skip it.
git -C /Users/bmandal/work/ai/guide add modules/
git -C /Users/bmandal/work/ai/guide status
Review what will be committed. Then commit:
git -C /Users/bmandal/work/ai/guide commit -m "sync: apply changes from vz-cnf-best-practices-guide (<YYYY-MM-DD>)"
git -C /Users/bmandal/work/ai/guide push -u origin sync/vz-<YYYY-MM-DD>
Build the PR body from the accepted changes. For each accepted change include:
Create the PR:
cd /Users/bmandal/work/ai/guide && gh pr create --title "Sync changes from VZ CNF guide (<YYYY-MM-DD>)" --body "$(cat <<'EOF'
## Summary
Synced documentation changes from vz-cnf-best-practices-guide to the public guide.
**Source:** vz-cnf-best-practices-guide @ `<private-commit-range from report header>`
## Changes Included
<For each accepted change, list:>
### `<public-filename>`
- **Source:** `<private-filename>`
- **Classification:** <reason>
- **Reviewer Notes:** <notes or "None">
## Review Process
Changes were classified by AI content analysis and reviewed manually using the cnf-doc-sync skill. Verizon-specific content was filtered out. Mixed content was either stripped of VZ references or rewritten by the reviewer.
EOF
)"
Tell the user the PR URL and a summary:
cnf-best-practices references that may need manual cleanup in the PRFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.
npx claudepluginhub bnshr/cnf-doc-sync-tool --plugin cnf-doc-sync