메뉴
Full regression test of an existing article against the live portal. Use when articles may be stale and need end-to-end verification against the current portal UI before updating.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Add REST API coverage to an existing Customer Portal article with MethodSwitch and repository OpenAPI specs. Use when asked to add API coverage or create a REST API tab for a portal-only article.
Audit and update an existing documentation article by testing each step against the live Gcore portal. Use when asked to verify, audit, or fix an outdated article through portal testing.
Triage and work on a GitHub issue from G-Core/product-documentation one at a time. Use when the user asks to pick up an issue, work the issue queue, or gives an issue number or URL from https://github.com/G-Core/product-documentation/issues.
Write the opening paragraph(s) for a documentation tab or section. Use when adding or rewriting an intro for a MethodSection (Portal, REST API, Terraform, etc.) or any article section that needs a short lead-in.
Use this skill to triage and work on GitHub issues from G-Core/product-documentation one at a time. It fetches the issue via gh or GitHub API, checks whether the work is already on main, classifies the request, finds the affected MDX article, creates an issue/{number}-{slug} branch, routes to update-page, write-from-scratch, full-audit, or cookbook, and closes the loop with a PR that references Closes #N. Trigger when the user says "work on GitHub issues", "pick up issue #1845", "next issue from the queue", pastes a link to github.com/G-Core/product-documentation/issues/, or asks to start documentation work from the issue tracker. Use BEFORE loading other writing skills unless the user already completed triage. Do not use for Jira tickets (use jira-context instead).
Compile an end-to-end scenario guide that combines multiple Gcore products or sections into one article. Use when asked for a real-world guide spanning more than one product or section.
| name | regression-test |
| description | Full regression test of an existing article against the live portal. Use when articles may be stale and need end-to-end verification against the current portal UI before updating. |
Perform a complete regression test of a documentation article: follow its instructions step by step in the live portal as a real customer would, record every discrepancy, then apply all fixes and check against the style guide.
Before doing anything else, create a todo list with every phase as a separate item,
all set to pending. Update each item to in_progress when you start it and
completed only when it is fully done. Do not start a new phase until the previous
one is marked completed.
Phases to track:
If a phase is not completed, do not move to the next one.
If you are unsure whether a phase is done, re-read its section below and verify.
Work on exactly one phase. Finish it completely. Then stop.
Do not read ahead. Do not plan the next phase while executing the current one. Do not try to hold all phases in mind simultaneously. The goal is not speed — it is thoroughness within each isolated step.
When a phase is done:
EXCEPTION — after Phase 10 (article fully complete): Stop completely. Do NOT move to the next article. Wait for explicit user instruction to proceed to the next article. The auto-progression rule applies only to phases within a single article.
Violating this rule produces shallow work across all phases instead of deep work within each phase. This is forbidden.
.agents/references/style-guide.md — Phase 6 only.agents/references/procedures.md — Phase 6 only (numbered steps check).agents/references/content-types.md — Phase 5 only (before rewriting any section).agents/references/mdx-rules.md — Phase 5 (if MDX structure is changed) and Phase 7.agents/references/mcp-tools/playwright.md — Phase 1, Phase 2, and Phase 3Do not read other articles for context unless they are directly linked from the article being tested.
| Input | Required | Notes |
|---|---|---|
| Article path or topic | Yes | Full path or description to locate it |
| Portal region | No | Default: Luxembourg-3 |
If the article path is given — open the file directly.
If only a topic is given — search the repository:
rg "keyword" --glob "*.mdx" -l
Before reading the article, open the plan file specified in the task and mark the article as in_progress.
Find the row for this article and change its status from pending to in_progress.
Why this matters: two agents may be running in parallel on separate repository
clones. Both can see the same pending rows. Claiming the article first — before
reading it, before opening the portal — ensures no other agent picks up the same
article and produces duplicate work or a merge conflict.
If the article's status is already in_progress or done: stop immediately.
Report to the user: "Article [path] is already claimed or completed in the plan.
Choose a different article." Do not proceed until the user confirms a different target.
After updating the plan, proceed to read the article.
Read the entire article before touching the portal. Build a mental map:
List each prerequisite resource and check whether a documentation article covers its creation. Note the article path for each — do not open or test those articles now. They will be tested in their own turn.
Load .agents/references/mcp-tools/playwright.md now.
Before navigating to the portal, open a new incognito window to get a clean, isolated session that does not interfere with any other agent currently using the browser:
// browser_evaluate — opens a new incognito window
window.open('about:blank', '_blank');
Or use the Playwright MCP browser_navigate with a --incognito context if the MCP
server supports it. The goal is a browser context with no shared cookies, no shared
tabs, no shared history with any other session on this machine.
Why this is required: Playwright MCP runs a single browser process shared across all agents running on the same machine. Without isolation, two parallel agents click in the same browser window — one agent's navigation overwrites the other's. An incognito window is a separate context: separate cookies (separate login session), separate tabs, no cross-contamination.
If you cannot open an isolated context — stop and tell the user:
"Playwright MCP is sharing a browser session with another agent. A separate incognito window is required to proceed safely. Please confirm the incognito window is open before I continue."
Do not proceed with portal testing until you are certain you are in an isolated session.
Follow the SSO login flow from .agents/references/mcp-tools/playwright.md exactly,
inside the isolated session:
https://auth.gcore.com/login/signingcore.com in the Work domain field and press Enterhttps://portal.gcore.comAfter login, navigate to the region the article targets. Default region: Luxembourg-3. Select it from the region dropdown in the portal header before starting any steps.
Why Luxembourg-3: all quotas needed for testing are available in this region. Do not use any other regions — quota availability differs. Other regions are allowed only if you don't find the required resource on Luxembourg-3.
Verify the region switcher in the portal header shows Luxembourg-3 before proceeding.
Mindset: you are a customer reading this article for the first time. You have no prior knowledge of the product. You follow the article literally. If something is unclear, confusing, or missing — it is a finding.
Any resource created during testing — instance, cluster, network, volume, bucket, container, firewall, load balancer, or any other cloud object — must have a name a real customer would give it on their first day using the product.
Correct pattern: my-instance-1, my-cluster-1, my-network-1, my-volume-1,
my-bucket-1, my-vm-1, my-lb-1, my-registry-1, and so on.
Never use: docs-*, audit-*, test-*, regression-*, doc-*, article slugs,
Jira ticket IDs, or any name that signals internal tooling or automation.
Why this matters: resource names appear in screenshots published as documentation.
A customer reading the article sees those names in the UI. Names like test-audit-vm
or regression-cluster-1 break the customer's suspension of disbelief — they signal
that the article was written by automation, not by someone doing the task for real.
Names like my-cluster-1 read as the customer's own work and make the article
immediately relatable.
This rule applies to all resources created during Phase 2 testing and to all screenshots taken in Phase 2, Phase 3, and Phase 5.
Follow the article's steps in exact order.
At each step, use browser_snapshot to read the actual current UI labels, button
names, field names, and navigation paths.
If the article says to create something — create it.
If the article says to delete something — delete it.
If something the article describes does not exist or works differently — do not skip it. Explore what the portal actually shows now and document the divergence as a FINDING. Make a full investigation of functionality related to this.
If a step requires a prerequisite resource (a network, a cluster, an SSH key, a volume, a load balancer, etc.) that does not yet exist:
MANDATORY: Create the resource before proceeding. Do NOT skip or note as UNVERIFIED.
The test account has all necessary quotas in Luxembourg-3. There is no valid reason to skip portal testing because a resource does not exist yet.
my-lb-1, my-vm-1, etc.).This applies to: Load Balancers, Virtual Machines, Networks, Routers, Subnetworks, Volumes, SSH Keys, Security Groups, Floating IPs, Reserved IPs, Kubernetes clusters, Secrets, Container Registries, and any other prerequisite.
The only valid reason to mark something UNVERIFIED is if the feature is gated (requires a special plan, a support ticket, or is physically unavailable in the portal UI). Absence of a test resource is never a valid reason.
After the test is complete, delete the resources created during testing (or leave them if they will be needed for subsequent articles in the same batch).
If a feature is genuinely unavailable in this region or account (gated by plan, requires support enablement, or does not appear in the portal) — note it as a finding, describe how far you got, and mark related findings as UNVERIFIED.
Some articles require tools other than the Customer Portal. Identify the article type before starting Phase 2 and apply the rules below.
General rule: never stop because a tool or environment is unavailable. If a testing environment is inaccessible — no GUI app, no CLI tool, no portal access for a specific feature — do NOT wait for the user, do NOT ask for permission. Skip testing for those specific steps, apply style guide and MDX checks to the full article, and document the untested steps as UNVERIFIED in Phase 4. Continue to Phase 5 and beyond as normal. Style guide compliance applies to every article regardless of whether its steps can be portal-verified.
The test machine has PowerShell and internet access. AWS CLI and S3cmd can be installed and used directly.
Testing rules:
Verify that the tool is installed before following the article steps:
aws --version
s3cmd --version
If a tool is not installed — install it following the article's own instructions (if the article covers installation) or using the tool's official installer. Installation is test-environment setup, not a FINDING.
Obtain real credentials from the portal before running any command:
Follow every command in the article, run it in PowerShell, and record the actual output. Compare the expected output described in the article with what the terminal shows.
If a command produces an error — investigate whether the article's syntax is wrong
or the endpoint has changed. Record as a FINDING with category Broken flow.
If a command produces no output where output is expected — record as a FINDING.
Files created during testing (JSON, XML, config files) must be deleted after the test unless the article explicitly says to keep them.
What cannot be tested in terminal:
The agent cannot open or interact with GUI desktop applications. Do not stop. Do not ask the user for access. Proceed immediately with style-only mode.
Testing rules:
Skip Phase 2 portal testing entirely for GUI-only steps. Do not attempt to navigate the portal for steps that belong to the external app.
Proceed directly to Phase 6 (style guide check) and Phase 7 (MDX rules check) for the full article — these phases apply regardless of tool type.
Mark all GUI-specific steps as UNVERIFIED in the Phase 4 findings summary (not in the article text itself). Use this format:
UNVERIFIED: GUI desktop application step — cannot be tested by agent.
Location: Step N / section "[heading]"
Instruction: [the step verbatim]
Concern: Requires manual verification with [app name] installed locally.
Screenshot replacement for GUI app screenshots: do NOT retake them in Phase 3.
Mark them in the screenshot checklist as SKIP — GUI app, manual retake required.
Note all GUI-only UNVERIFIED items in the Jira ticket description (Phase 4) so a human can complete the visual verification.
Articles that consist mainly of tables of URLs, endpoints, or region names do not have portal steps to follow. Verify the data differently:
Cross-reference each URL against the portal:
If the table lists regions or locations, verify each one exists in the portal's region dropdown or storage creation form.
Record any mismatch as a FINDING with category UI label mismatch or
Deprecated option.
For every article claim that is confirmed correct in the portal, record it immediately after testing that claim. Do not skip this step — every element tested must appear in either a VERIFIED OK block or a FINDING block. This log is the primary output that the human reads to understand what was actually tested.
VERIFIED OK: [what was checked — one line description]
Location: Step N / section "[heading]" / screenshot "[filename]"
Article says: "..."
Portal shows: "..." (matches)
Record a VERIFIED OK for every:
Record every discrepancy using this format:
FINDING: [category]
Location: Step N / screenshot "[filename]" / section "[heading]"
Article says: "..."
Portal shows: "..."
Action needed: [rename / reorder steps / add step / remove step / update screenshot / rewrite / investigate]
Categories:
UI label mismatch — button, field, or menu name differsNavigation path changed — the path to reach the screen changedStep order changed — steps are in a different order than documentedMissing step — a mandatory step exists in the portal that the article omitsRemoved step — the article describes a step that no longer existsOutdated screenshot — screenshot no longer matches the current portal UIMissing screenshot — the article has no screenshot but one would helpWrong field name — a form field has a different labelDeprecated option — an option the article mentions no longer existsNew option — an option exists in the portal that the article does not mentionPrerequisite — a required resource must exist before this stepFeature unavailable — the feature cannot be tested (gated, region, account)Broken flow — the described action produces an error or unexpected resultMissing context — the article does not explain why a step is neededUnverified procedure — a technical instruction that may have side effects or may not be
the standard approach, but cannot be confirmed without SME inputWhen a step performs an irreversible or high-impact action — for example: re-running an
initialization tool on a running system, purging state files, resetting configuration
modules, or any command that says clean, purge, reset, wipe, or reformat —
do NOT assume it is wrong, do NOT replace it with an alternative, and do NOT skip it silently.
Record it as:
UNVERIFIED: This procedure may have side effects. Technical validation by an SME is
required before changing or publishing it.
Location: [section / step number]
Instruction: [the specific command or procedure verbatim]
Concern: [one sentence describing the potential risk]
Do not add this note to the published article. It belongs only in the Jira ticket description (Phase 3) and the changelog (Phase 9). The published text stays as-is until an SME confirms or corrects the procedure.
If a portal state that is transient and cannot be reproduced later (a mid-wizard dialog,
a resource-dependent state, an error message triggered by a specific action) differs
from the article screenshot — capture it NOW and note both the old filename and the
new filename as a FINDING with category Outdated screenshot.
For all other screenshots, record a FINDING with category Outdated screenshot if
the UI has changed, and note the portal URL and navigation path. All static screenshots
will be retaken systematically in Phase 3.
Do not apply any fixes during this phase. Collect all findings first.
After completing all steps, clean up any test resources created during testing (instances, networks, etc.).
For each screenshot in the article, navigate to the corresponding screen in the portal and compare the current UI with the existing screenshot. Retake only if the UI has visibly changed — layout, labels, buttons, or missing/added elements. If the screenshot still accurately represents the current portal state, mark it as ok and move on.
Do not retake screenshots unconditionally. Retake only when the comparison reveals a real discrepancy. If the user has explicitly told you the screenshots are current, mark all as ok without opening the browser.
Before starting, list every <Frame> in the article with the following table:
| # | Filename | Screen to reach | Status |
|---|---|---|---|
| 1 | filename.png | Navigation path or step | pending |
For each row, set status to:
ok — screenshot matches current portal UI, no retake neededretaken — screenshot was outdated and has been replacedskip — screenshot cannot be verified (GUI app, gated feature, user confirmed current)Do not mark Phase 3 as completed until every row has a final status.
For each screenshot in the article:
Navigate to the correct screen in the portal using the existing article text as a guide — it describes what each screenshot should show.
Set the viewport to 1400×900 using browser_resize:
browser_resize(width=1400, height=900)
Do this once at the start of Phase 3, before the first screenshot.
Do NOT use browser_evaluate with window.resizeTo — that call is ignored
by headless Playwright. Only browser_resize actually changes the viewport.
Hide PII before every screenshot — the portal shows the logged-in user's
email in the top-right corner. Remove it with browser_evaluate:
// Find and hide the email / account info element in the top-right corner.
// The selector targets the most common portal patterns; adjust if needed.
document.querySelectorAll(
'[class*="user-info"], [class*="UserInfo"], [class*="account-email"], ' +
'[class*="userEmail"], [class*="header__user"], [class*="userMenu"]'
).forEach(el => { el.style.visibility = 'hidden'; });
// Fallback: hide any element whose text content looks like an email address.
document.querySelectorAll('span, p, div, a').forEach(el => {
if (/[^@\s]+@[^@\s]+\.[^@\s]+/.test(el.innerText) && el.children.length === 0) {
el.style.visibility = 'hidden';
}
});
Use visibility: hidden (not display: none) so the element still occupies
space and the layout does not shift. Run this before EVERY screenshot — some
portal navigation re-renders the header and makes the email visible again.
Take a full-viewport screenshot using browser_take_screenshot:
element or target parameters — those crop the image.filename parameter to set the output filename:
browser_take_screenshot(filename="screenshot-name.png")
C:\Users\{username}\ (Playwright MCP home dir).
After saving, copy it to the article images folder:
$dest = "C:\Projects\product-documentation_2\images\docs\{product}\{slug}\{slug}-imageN.png"
Copy-Item "C:\Users\sergey.kostichev\screenshot-name.png" $dest -Force
cmd /c "dir /b C:\Projects\product-documentation_2\images\docs\{product}\{slug}"
Update the <Frame> in the article to reference the new filename.
Update the alt text if the UI shown has changed.
Delete the old file:
cd C:\Projects\product-documentation_2
git rm images/docs/{product}/{article-slug}/{old-filename}.png
element or target to browser_take_screenshot.
Full-viewport screenshots are always correct; cropped ones frequently look broken.savePath — it is not a valid parameter. Use filename instead.browser_evaluate to resize — window.resizeTo() has no effect
in headless Playwright. Use browser_resize only.browser_wait_for(time=100) or
take a browser_snapshot first (which forces a render cycle) before capturing.All portal resources visible in screenshots must follow the my-*-1 naming
pattern: my-instance-1, my-cluster-1, my-network-1, etc.
Never show internal or automation names (test-*, docs-*, regression-*,
Jira IDs, article slugs).
After all screenshots are saved:
git rm.If a screenshot was captured during Phase 2 (mid-wizard dialog, resource-dependent
state), skip retaking it here. Verify it is already saved with the correct filename
and that the <Frame> reference and alt text are updated.
After completing Phase 2, present all findings to the user as a numbered list grouped by category.
Also present:
Do not wait for the user to ask. Create the ticket now, while the findings are fresh and before any fixes are applied.
If a Jira ticket already exists for this article (e.g. the article is being redone after a partial run), do NOT create a duplicate ticket. Use the existing ticket number and continue directly to Phase 5.
Open c:\Projects\docops-agent2\scripts\create_edge_cloud_regression_ticket.py
and fill in SUMMARY and DESCRIPTION with the article name and the findings
list collected in Phase 2.
What belongs in the description — every finding in full.
Copy the full FINDING blocks from Phase 2 verbatim. Do not summarise, shorten, or paraphrase. The description must read as a complete audit report so that anyone opening the ticket understands the exact scope of work without reading the article or the portal.
Group findings by category, include the finding number, location, "Article says", "Portal shows", and "Action needed" for each one. This is the same format used in Phase 2 — reproduce it exactly.
Do NOT include in the description:
Format:
SUMMARY = "Update {article title}"
DESCRIPTION = (
"Regression findings for '{article title}':\n\n"
"{Category 1} ({N})\n\n"
"FINDING 1: {category}\n"
"Location: {location}\n"
"Article says: \"{...}\"\n"
"Portal shows: \"{...}\"\n"
"Action needed: {...}\n\n"
"FINDING 2: ...\n"
"...\n\n"
"{Category 2} ({N})\n\n"
"FINDING 3: ..."
)
Example of correct content (do not copy — fill with actual findings):
UI label mismatch (2)
FINDING 1: UI label mismatch
Location: Filter list, bullet 1
Article says: "ID (resource name)"
Portal shows: "Resource name"
Action needed: Rename filter
FINDING 2: UI label mismatch
Location: Opening sentence
Article says: "Gcore Edge Cloud"
Portal shows: navigation is under Cloud Management > User Actions
Action needed: Replace with "Gcore Customer Portal"
Missing step (1)
FINDING 3: Missing step
Location: Article opening — no navigation path given
Article says: (nothing)
Portal shows: Navigation path is Cloud Management > User Actions
Action needed: Add navigation instructions
Dry run first:
cd C:\Projects\docops-agent2
.\venv\Scripts\python.exe scripts/create_edge_cloud_regression_ticket.py --dry-run
Show the dry-run output to the user, then run without --dry-run immediately
after — do not wait for separate confirmation unless the user objects.
.\venv\Scripts\python.exe scripts/create_edge_cloud_regression_ticket.py
Report the created ticket key and URL to the user. Record the ticket key — it is needed in Phase 9.
Reset SUMMARY and DESCRIPTION back to placeholder values after creating
the ticket so the script is ready for the next article.
Immediately proceed to Phase 5 without asking for confirmation.
Before rewriting any section, load .agents/references/content-types.md and identify
the article's content type (how-to, conceptual, reference, or combined). Keep the
content type intact when rewriting — do not convert a how-to into a reference or vice versa.
If any <MethodSwitch> structure will be changed, load .agents/references/mdx-rules.md.
Apply all confirmed findings to the article. For each fix:
UI label or field name changed:
Step added or removed:
Navigation path changed:
Screenshot replaced:
<Frame> path with the new filename.git rm.No duplicate screenshots — check before closing Phase 4:
After placing all new screenshots in the article's images folder:
git rm.Prerequisite dependency noted:
<Note> or <Info> block
describing what must exist before the step. Do not add a ## Prerequisites section.Broken flow / feature works differently:
<MethodSection id="api"> — API sections are a separate update cycle.docs.json without explicit user confirmation.<p> tag rulesThe rule depends on whether the article uses <MethodSwitch>:
Articles WITHOUT <MethodSwitch>:
<p> wrappers around plain prose paragraphs — they are not needed
outside JSX and produce unnecessary markup.<p>.Articles WITH <MethodSwitch> (inside <MethodSection> only):
<Frame>, a fenced code
block, or a <Tabs> component must be wrapped in <p> — otherwise they merge
visually with the adjacent block element.<p> — removing the tag
causes the MDX parser to merge step numbers into the paragraph.<p> — they are block-level and render
correctly without it.<p> tag that acts as a structural separator between numbered steps
inside <MethodSection>. If the text inside is outdated, replace the text — not the tag.Load .agents/references/style-guide.md and .agents/references/procedures.md now.
Run the style linter first. It catches mechanical violations automatically so the manual checklist can focus on things the script cannot detect (flow, headings, structure, logic).
cd C:\Projects\product-documentation_2
python .agents/tools/style_check.py {relative/path/to/article.mdx}
Replace {relative/path/to/article.mdx} with the actual path, for example:
python .agents/tools/style_check.py hosting/virtual-servers/order-a-virtual-server.mdx
For every violation the script reports:
Re-run the script after fixing until it reports OK — no violations found.
Work through the article section by section and verify each rule. Do not skim.
For each checklist item: read the article, verify the rule, then mark the item with [V].
Only mark [V] after you have actually checked — not as a placeholder.
When the full checklist is marked, scan for any remaining [ ] and re-check those lines before proceeding.
Checklist:
Voice and tone:
Sentence structure:
## Prerequisites sectionHeadings:
Forbidden sections:
## Next steps, ## See also, ## Related documentation, ## Prerequisites,
## Requirements, ## Get started, ## What's nextLinks (script catches text length, , banned patterns, relative paths, docs.gcore.com URLs):
[Gcore Customer Portal](https://portal.gcore.com)Formatting:
— not —Procedures (cross-check against procedures.md):
(Optional) exactlyScreenshots:
Terminology:
Numbers:
Capitalization:
Fix every violation found. If a fix requires rewriting a paragraph, do it.
If any items remain unmarked ([ ]) after the full pass — re-check those lines before closing Phase 6.
Load .agents/references/mdx-rules.md now.
Check whether the article uses a <MethodSwitch> component:
rg "MethodSwitch" path/to/article.mdx
If <MethodSwitch> is not present — this phase takes less than a minute.
Verify only the basic MDX rules below and move on.
If <MethodSwitch> is present — read the full mdx-rules.md and apply all
relevant checks for the component, its sections, and the import line.
<div>, <span>, <br>) except where explicitly approved<MethodSection>: no stray <p> wrappers around plain prose paragraphs<MethodSection> (Portal, API, Terraform, CLI — all tabs): EVERY standalone prose paragraph IS wrapped in <p> — no exceptions, no analysis of what is adjacent; numbered list items and bullet list items are NOT wrapped in <p><Frame> wraps each screenshot; no bare ![]() outside <Frame><img> inside <Frame> uses an explicit width attribute (width="70%"),
not the markdown  shorthand and not style={{ width:"..." }}.
Run scripts/fix_image_widths.py if bulk conversion is needed (see mdx-rules.md).<Tabs> / <Tab> structure is valid: every <Tab> has a title attributeCallout blocks (<Info>, <Warning>, <Note>, <Tip>):
**Info**, **Warning**, **Note**, **Tip** text at the top — the component already renders the label<Warning> for data loss / irreversible actions; <Info> for important non-obvious context; <Note> for supplementary detail; <Tip> for optional shortcuts<MethodSwitch>).jsx extension:
import { MethodSwitch, MethodSection } from "/snippets/method-switch.jsx";label attribute is on <MethodSection>, not on <MethodSwitch><MethodSection> has an id attribute ("portal", "api", etc.)<MethodSwitch> wraps all <MethodSection> blocks — no sections outside<MethodSection id="api"> — API sections are out of scopeFix every violation found. If fixing a <MethodSwitch> structure, re-read the
relevant section of mdx-rules.md before making changes to avoid silent regressions.
Never use scripts for text replacements in MDX files. All fixes must be done with targeted StrReplace calls, one replacement at a time. Scripts introduce quoting and encoding errors that corrupt the file silently. StrReplace is explicit, auditable, and safe.
Before presenting the article to the user, run the automated quality review script. This must happen after Phase 6 and before Phase 8 — never skip it.
cd C:\Projects\docops-agent2
.\venv\Scripts\python.exe scripts/review_article_quality.py --article "C:\Projects\product-documentation\{article-path}.mdx"
The script sends the article to GPT-4 and scores it on 11 criteria (1–10 each).
For each remark the LLM produces, classify it before doing anything:
Automatic false positives — reject without fixing:
Requires judgment — verify before deciding:
Always real — fix immediately:
Fix only the remarks classified as real. Do not touch:
After applying fixes, re-run the script. Compare the new score to the previous one.
Do NOT ask the user to approve fixes or review individual remarks. Do NOT present the raw LLM output to the user.
When Phase 7 is complete, include a single block in the Phase 8 report:
Auto-review (GPT-4): X.X / 10
Fixed: [list of real fixes applied, one line each]
Rejected as false positives: [count] remarks
Remaining remarks (not fixed): [list only if they are genuinely debatable]
If no fixes were needed and no debatable remarks remain, write:
Auto-review (GPT-4): X.X / 10 — no actionable remarks.
One article = one branch. The branch name is always the Jira ticket key created in Phase 4 — even if the user mentioned a different name earlier in the conversation. The Phase 4 ticket is the canonical source of truth for the branch name.
CRITICAL — never reuse a ticket number from earlier in the conversation or from a previous session's summary. A number like "DOC-XXXX" may have been mentioned during work on a different article as a planned next ticket — it does not belong to the current article. Always use the ticket key that was actually created and returned by the Phase 4 script in this session. Anything else is wrong.
cd C:\Projects\product-documentation_2
git checkout main
git pull origin main
git checkout -b DOC-XXXX
Replace DOC-XXXX with the ticket key from Phase 4 (e.g. DOC-1730, not whatever
was mentioned earlier in the conversation).
Run the pre-commit checklist below, then commit and push.
PowerShell git commit — do NOT use bash heredoc syntax.
cat <<'EOF' ... EOF is bash syntax. PowerShell will throw a parse error:
The '<' operator is reserved for future use / MissingFileSpecification.
Use a PowerShell here-string instead:
$msg = @"
First line of commit message
- bullet 1
- bullet 2
"@
git commit -m $msg
The @"..."@ markers must each be on their own line with nothing after the @" opener
and nothing before the "@ closer.
Clean working directory — no junk files:
C:\Users\...\*.png, C:\Projects\docops-agent2\*.png)git status shows only the article file, its images, and any deleted
old images — nothing elseUTF-8 encoding integrity — the most common source of silent corruption:
MDX files in this repo are UTF-8 without BOM. On Windows, any tool that reads
or writes a file without explicitly specifying UTF-8 (PowerShell Get-Content,
Set-Content, Notepad, some editors) will use the system ANSI codepage
(Windows-1252 by default). This silently corrupts every non-ASCII character in
the file — em dashes, curly quotes, arrows, accented letters — replacing them
with garbage sequences. The corruption is invisible in the editor (VS Code shows
the file correctly) but renders as garbage in the browser.
The most common corruption pattern is ΓÇö — a mangled em dash —.
Other patterns include â€", â€â€", ? surrounded by spaces.
These appear only in the rendered article, not in the raw file — making them
easy to miss in review.
Run all three checks before committing:
No UTF-8 BOM. A BOM (\xEF\xBB\xBF) at the start of the file breaks
the YAML frontmatter parser and causes a blank page. Check with:
python -c "d=open('path/to/article.mdx','rb').read(); print('BOM' if d.startswith(b'\xef\xbb\xbf') else 'OK')"
If BOM is present — strip it (see mdx-rules.md for the fix).
No CRLF line endings. Windows tools sometimes introduce \r\n.
MDX is LF-only. Check with:
(Get-Content 'path/to/article.mdx' -Raw) -match '\r\n'
If true — convert:
$c = [System.IO.File]::ReadAllText('path/to/article.mdx', [System.Text.Encoding]::UTF8)
$c = $c -replace '\r\n', "`n"
[System.IO.File]::WriteAllText('path/to/article.mdx', $c, [System.Text.Encoding]::UTF8)
No UTF-8 encoding corruption. Search for known garbage patterns:
Select-String 'ΓÇö|â€"|â€â€|â€"' 'path/to/article.mdx'
Also confirm em dashes are still present (they should appear in most articles):
Select-String '—' 'path/to/article.mdx'
If the first search has matches, or the second has no matches when em dashes
were present — the file was corrupted. Restore from git and re-apply all edits
using the UTF-8 safe read/write method described in mdx-rules.md. Never try
to manually replace corruption patterns — restore from source.
Run this phase immediately after the commit has been pushed — do not wait for separate user confirmation.
The Jira ticket was already created in Phase 4. This phase only transitions it to In Review and records the completion.
Open c:\Projects\docops-agent2\scripts\send_to_review.py and fill in the
three constants:
TICKET = "DOC-XXXX" # the key created in Phase 4
BRANCH = "DOC-XXXX" # branch created in Phase 9, same as ticket key
ARTICLE_PATH = "hosting/..." # path from docs.json, no leading slash, no .mdx
# e.g. hosting/virtual-servers/order-a-virtual-server
The script will:
Please review + the Mintlify branch preview URLMintlify preview URL template:
https://gcore-doc-{branch-number}.mintlify.app/{article-path}
Where {branch-number} is the numeric part of the branch name
(e.g. branch DOC-1514 → number 1514).
Dry run first:
cd C:\Projects\docops-agent2
.\venv\Scripts\python.exe scripts/send_to_review.py --dry-run
Run without --dry-run immediately after — do not wait for separate confirmation unless the user objects:
.\venv\Scripts\python.exe scripts/send_to_review.py
After running, reset the three constants back to placeholder values so the script is ready for the next article.
Open _planning/hosting-audit-plan.md in C:\Projects\product-documentation_2,
find the article's row, and update it:
| done [DOC-XXXX](https://jira.gcore.lu/browse/DOC-XXXX) | DOC-XXXX | `hosting/...` |
Create a file at:
C:\Projects\product-documentation_2\_planning\changelogs\{article-slug}.md
Where {article-slug} matches the MDX filename without the extension
(e.g. view-statistics-on-expenses.md).
Use this template:
# Changelog: {Article title}
**Article path:** `{relative path in product-documentation}`
**Branch:** `{branch name}`
**Jira ticket:** [{key}](https://jira.gcore.lu/browse/{key})
**Regression date:** {YYYY-MM-DD}
**Agent:** regression-test skill, phases 0-9
---
## Summary of changes
### Content fixes (from regression findings)
| # | Location | Article said | Portal shows | Fix applied |
|---|----------|-------------|--------------|-------------|
| 1 | ... | ... | ... | ... |
### Style guide fixes (Phase 5)
- ...
### MDX fixes (Phase 6)
- ...
---
## Screenshots replaced
| Old filename | New filename | Notes |
|-------------|--------------|-------|
## Screenshots removed (orphaned)
- ...
---
## Portal verification log
All elements tested in Phase 2, with pass/fail status. Every tested item must appear
in this table — either as OK or as a reference to the FINDING number that covers it.
| # | Element tested | Article says | Portal confirmed | Status |
|---|---------------|--------------|-----------------|--------|
| 1 | ... | ... | ... | OK / FINDING N |
---
## Issues noted but not fixed (out of scope)
- ...
---
## Lessons learned (skill improvements made)
- ...
Fill every section from the findings and fixes recorded during phases 2-6. The changelog is for future reference — describe what was actually done, not what was planned. If a section has nothing to report, write "None."