chore: update GFIC guidelines

Signed-off-by: exploreriii <[email protected]>

Author: exploreriii

docs/maintainers/good_first_issue_candidate_guidelines.md

@@ -1,199 +1,130 @@
 # Good First Issue — Candidate Guidelines
 
-This document explains the purpose of the **`good first issue: candidate`** label, when to use it, and when an issue should be promoted to a full **Good First Issue**.
+This document defines the purpose and usage of the **`good first issue: candidate`** label, and explains when and how an issue may be promoted to a full **Good First Issue (GFI)**.
+
+The candidate label exists to protect the quality and trustworthiness of **Good First Issues** by ensuring issues are **fully specified, low-risk, and mechanically solvable** before being promoted.
+
+---
 
 ## Table of Contents
 
-- [Why We Use a "Candidate" Label](#-why-we-use-a-candidate-label)
-- [When to Use the Candidate Label](#️-when-to-use-good-first-issue-candidate)
-- [What a Candidate Is NOT](#-what-a-candidate-is-not)
-- [Promoting a Candidate to GFI](#-promoting-a-candidate-to-gfi)
-- [Workflow Summary](#-workflow-summary)
-- [Important Considerations](#important-considerations)
+- [Why We Use a Candidate Label](#why-we-use-a-candidate-label)
+- [When to Use `good first issue: candidate`](#when-to-use-good-first-issue-candidate)
+- [What a Candidate Is NOT](#what-a-candidate-is-not)
+- [Promoting a Candidate to GFI](#promoting-a-candidate-to-gfi)
 
 ---
 
-## 🎯 Why We Use a "Candidate" Label
+## Why We Use a Candidate Label
 
 Labeling an issue as a **Good First Issue (GFI)** signals to new contributors that the issue is:
 
-- ✅ **Well-scoped** — clear boundaries and deliverables
-- ✅ **Low risk** — minimal chance of breaking changes
-- ✅ **Clearly defined** — unambiguous requirements
-- ✅ **Ready to be picked up** — with minimal guidance needed
+- ✅ Small and well-scoped
+- ✅ Low risk
+- ✅ Fully specified
+- ✅ Safe for first-time contributors
+- ✅ Ready to be picked up without interpretation or initiative
+
+However, **many issues are not ready for that label immediately**.
+
+They might have:
+- ❗ Incomplete documentation
+- ❗ Uncertainty if they are in fact a good first issue
 
-However, **not all issues start in that state**.
 
 The **`good first issue: candidate`** label exists to:
 
 | Purpose | Description |
-|---------|-------------|
-| 🚫 **Avoid premature labeling** | Prevent issues from being labeled as GFIs before they're ready |
-| 🔍 **Allow refinement time** | Give maintainers space to clarify scope and requirements |
-| 📊 **Set accurate expectations** | Ensure new contributors know exactly what to do |
-| 📋 **Create a clear pipeline** | Establish a workflow for curating high-quality GFIs |
+|--------|-------------|
+| 🚫 Avoid premature labeling | Prevent partially defined or misclassified issues from being advertised as GFIs |
+| 🧭 Enforce quality standards | Ensure GFIs meet strict “no interpretation required” criteria |
+| 🛠 Allow refinement time | Give maintainers space to fully specify scope and solution |
+| 📋 Create a clear pipeline | Establish a safe promotion path to GFI |
 
-This approach helps us prioritize **quality over quantity** when advertising beginner-friendly work.
+The candidate label is **not a softer GFI** — it is a **holding state**.
 
 ---
 
-## 🏷️ When to Use `good first issue: candidate`
+## When to Use `good first issue: candidate`
 
-Apply the **candidate** label when an issue:
+Apply the **candidate** label when you believe the issue is a good first issue, not documented enough, or have some doubt with its difficulty:
 
-### ✅ Fits the General Criteria
+### ✅ Appears Potentially Suitable as a GFI
 
-- *Might* be suitable as a GFI based on initial assessment
-- Fits within the [allowed categories](./good_first_issues_guidelines.md#allowed-categories) of GFI work
-- Appears to be small in scope and low risk
+- The change is *likely* small, localized, and low risk
+- The issue fits within the **allowed GFI categories** (docs, examples, typing, small mechanical edits)
+- The issue is *not* exploratory and does *not* require design decisions
 
-### ⏳ Still Needs Work
+Suitability can be assessed [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md)
 
-- **Needs clarification** — requirements are ambiguous or incomplete
-- **Needs refinement** — scope could be narrowed or better defined
-- **Needs confirmation** — maintainer review required to verify suitability
-- **Needs acceptance criteria** — clear success conditions not yet defined
+### ✅ Requires Some Refinement
 
-### 📝 Example Scenarios
+One or more of the following is still missing:
 
-| Scenario | Why Use Candidate? |
-|----------|-------------------|
-| User reports a documentation gap | Needs scoping to determine exact changes required |
-| Bug in example code identified | Need to confirm it's isolated and straightforward to fix |
-| Type annotation improvement suggested | Need to verify it doesn't affect runtime behavior |
-| Test assertion missing | Need to confirm it extends existing tests only |
+- ❗ Explicit step-by-step instructions
+- ❗ Clearly defined acceptance criteria
 
----
-
-## 🚦 What a Candidate Is NOT
+### ✅ Difficulty is Uncertain
 
-The **candidate** label should **NOT** be used for:
+Use the `good first issue: candidate` label when you believe it is a Good First Issue but are not sure
 
-### ❌ Large or Cross-Cutting Changes
+- ✅ Requires maintainer approval
 
-Issues that span multiple modules, packages, or require architectural understanding.
+Check by reading good first issue guidelines [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md)
 
-### ❌ Core Protocol or SDK Logic
+If easy issues are not 'Good First Issues' are in fact 'beginner' issues.
 
-Changes to:
-- `to_proto` / `from_proto` methods
-- Serialization/deserialization logic
-- Network or wire-level behavior
+## What a Candidate Is NOT
 
-### ❌ Exploratory or Investigative Work
+The **candidate** label must **NOT** be used for issues that clearly do not qualify as GFIs.
 
-Issues where the solution path is unclear or requires research.
+### ❌ Not for Issues Requiring Decisions
 
-### ❌ Blocked Issues
+If a contributor must decide:
+- *what* to change
+- *how* something should behave
+- *what* is correct or expected
 
-Issues that depend on external decisions, other PRs, or upstream changes.
+→ the issue is **not** a candidate.
 
----
+### ❌ Not for Core or Behavioral Changes
 
-> ⚠️ **Important:** If an issue clearly does *not* meet GFI criteria, it should **not** be labeled as a candidate either. The candidate label is for issues that *might* qualify, not for issues that definitely won't.
-
----
+Do **not** use the candidate label for changes involving:
 
-## ✨ Promoting a Candidate to GFI
+- SDK or protocol behavior
+- Public APIs or contracts
+- `to_proto` / `from_proto` logic
+- Serialization, deserialization, or networking
 
-A candidate should be promoted to a full **Good First Issue** when:
+### ❌ Not for Exploratory or Blocked Work
 
-### Readiness Checklist
+- Investigations or debugging tasks
+- Issues dependent on other PRs or decisions
+- Work requiring domain or protocol knowledge
 
-- [ ] **Clear description** — the problem and solution are well-defined
-- [ ] **Scoped appropriately** — changes are localized and low-risk
-- [ ] **Acceptance criteria defined** — clear conditions for success
-- [ ] **Documentation linked** — relevant guides are referenced
-- [ ] **No blockers** — no dependencies on other work
-- [ ] **Maintainer approved** — a maintainer has reviewed and confirmed suitability
-
-### Promotion Process
-
-1. **Review the candidate issue** against [GFI guidelines](./good_first_issues_guidelines.md)
-2. **Add missing details** — clarify requirements, add acceptance criteria
-3. **Remove `good first issue: candidate`** label
-4. **Add `Good First Issue`** label
-5. **Optionally notify** in comments that the issue is ready for contributors
-
----
-
-## 📊 Workflow Summary
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Issue Created                            │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│              Initial Assessment by Maintainer               │
-│                                                             │
-│  Is this potentially a Good First Issue?                    │
-│                                                             │
-│  • Small scope?                                             │
-│  • Low risk?                                                │
-│  • Fits allowed categories?                                 │
-└─────────────────────────────────────────────────────────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              │               │               │
-              ▼               ▼               ▼
-         ┌────────┐     ┌──────────┐    ┌──────────┐
-         │   No   │     │  Maybe   │    │   Yes    │
-         └────────┘     └──────────┘    └──────────┘
-              │               │               │
-              ▼               ▼               ▼
-    ┌─────────────────┐ ┌───────────────┐ ┌───────────────┐
-    │ Label normally  │ │ Label as      │ │ Label as      │
-    │ (not GFI)       │ │ `candidate`   │ │ Good First    │
-    │                 │ │               │ │ Issue         │
-    └─────────────────┘ └───────────────┘ └───────────────┘
-                              │
-                              ▼
-                    ┌─────────────────┐
-                    │ Refine & Review │
-                    │                 │
-                    │ • Add details   │
-                    │ • Define scope  │
-                    │ • Set criteria  │
-                    └─────────────────┘
-                              │
-                              ▼
-                    ┌─────────────────┐
-                    │ Promote to GFI  │
-                    │ when ready      │
-                    └─────────────────┘
-```
+> ⚠️ If an issue clearly does *not* meet GFI criteria, **do not label it as a candidate**.  
+> The candidate label is for issues that *might* qualify after refinement — not for issues that never will.
 
 ---
 
-## Important Considerations
+## Promoting a Candidate to GFI
 
-### Why This Matters
+A candidate may be promoted to a full **Good First Issue** only when **all** of the following are true.
 
-1. **Good First Issues are automatically promoted** by GitHub and Hiero, making them highly visible to potential contributors worldwide
+### ✅ Readiness Checklist
 
-2. **New contributors trust the GFI label** — they expect issues to be ready and achievable
+- [ ] The problem is clearly described
+- [ ] The solution is **explicitly specified**
+- [ ] The change is small, localized, and low risk
+- [ ] The issue touches a single file or clearly defined location
+- [ ] Acceptance criteria are defined and objective
+- [ ] No interpretation or initiative is required
 
-3. **Poorly scoped GFIs waste contributor time** — and can discourage future contributions
+### 🔁 Promotion Process
 
-4. **Quality GFIs build community** — successful first contributions lead to long-term contributors
-
-### Best Practices
-
-| Do | Don't |
-|----|-------|
-| ✅ Use candidate for uncertain issues | ❌ Rush issues to GFI status |
-| ✅ Take time to refine candidates | ❌ Label obviously unsuitable issues as candidates |
-| ✅ Add clear acceptance criteria before promotion | ❌ Promote candidates without review |
-| ✅ Link to relevant documentation | ❌ Assume contributors know the codebase |
-
----
+1. Review the issue against the **Good First Issue Guidelines** [here](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/maintainers/good_first_issues_guidelines.md)
+2. Add missing details, steps, and acceptance criteria
+3. Remove the `good first issue: candidate` label
+4. Add the **Good First Issue** label
 
-## Additional Resources
 
-- [Good First Issue Guidelines](./good_first_issues_guidelines.md) — what qualifies as a GFI
-- [Contributing Guide](../../CONTRIBUTING.md) — how to contribute
-- [DCO Signing Guide](../sdk_developers/signing.md) — commit signing requirements
-- [Discord Community](../discord.md) — get help from the community
-- [Community Calls](https://zoom-lfx.platform.linuxfoundation.org/meetings/hiero?view=week) — weekly office hours