docs: refine issue refinement guidelines for clarity and structure

[oidacra]

• Updated ambiguity flagging section to clarify the importance of each ambiguity.
• Reorganized phases for better flow, renaming Phase 4 to 'Re-Analyze' and Phase 5 to 'Write Acceptance Criteria.'
• Enhanced writing process guidelines to emphasize outcome-focused criteria and clarity in acceptance criteria.
• Added examples to illustrate the refinement process and improve understanding.

These changes aim to improve the documentation's usability and ensure clearer communication of the refinement process.

Proposed Changes

• change 1
• change 2

Checklist

• Tests
• Translations
• Security Implications Contemplated (add notes if applicable)

Additional Info

** any additional useful context or info **

Screenshots

Original	Updated
** original screenshot **	** updated screenshot **

[github-actions]

❌ Issue Linking Required

This PR could not be linked to an issue. All PRs must be linked to an issue for tracking purposes.

How to fix this:

Option 1: Add keyword to PR body (Recommended - auto-removes this comment)
Edit this PR description and add one of these lines:

• This PR fixes #123 or Fixes: #123

• This PR closes #123 or Closes: #123

• This PR resolves #123 or Resolves: #123

• Other supported keywords: fix, fixed, close, closed, resolve, resolved
  Option 2: Link via GitHub UI (Note: won't clear the failed check)

1. Go to the PR → Development section (right sidebar)

2. Click "Link issue" and select an existing issue

3. Push a new commit or re-run the workflow to clear the failed check
   Option 3: Use branch naming
   Create a new branch with one of these patterns:

• 123-feature-description (number at start)

• issue-123-feature-description (issue-number at start)

• feature-issue-123 (issue-number anywhere)

Why is this required?

Issue linking ensures proper tracking, documentation, and helps maintain project history. It connects your code changes to the problem they solve.---

This comment was automatically generated by the issue linking workflow

[claude]

Claude finished @oidacra's task in 42s —— View job

---

Rollback Safety Analysis

• Read rollback-unsafe categories reference
• Get full PR diff
• Analyze diff against unsafe categories
• Apply appropriate label

---

Result: ✅ Safe to Rollback

The only changed file is .claude/skills/dotcms-github-issues/references/issue-refinement.md — a pure documentation update. Checked against all categories:

Category	Match?
C-1 Structural Data Model Change	❌ No
C-2 Elasticsearch Mapping Change	❌ No
C-3 Content JSON Model Version Bump	❌ No
C-4 DROP TABLE / DROP COLUMN	❌ No
H-1 One-Way Data Migration	❌ No
H-2 RENAME TABLE / COLUMN	❌ No
H-3 PK Restructuring	❌ No
H-4 New ContentType Field Type	❌ No
H-5 Storage Provider Change	❌ No
H-6 DROP PROCEDURE/FUNCTION	❌ No
H-7 NOT NULL Column Without Default	❌ No
M-1 Non-Broadening Column Type Change	❌ No
M-2 Push Publishing Bundle Format Change	❌ No
M-3 REST/GraphQL API Contract Change	❌ No
M-4 OSGi Plugin API Breakage	❌ No

No unsafe patterns found. Label AI: Safe To Rollback has been applied.