chore: update GFI guidelines with beginner level

Signed-off-by: exploreriii <133720349+exploreriii@users.noreply.github.com>

Author: exploreriii

docs/maintainers/good_first_issues_guidelines.md

@@ -5,223 +5,146 @@ This document defines what we **do** and **do not** consider a *Good First Issue
 ## Table of Contents
 
 - [Purpose](#purpose)
-- [Allowed Categories](#allowed-categories)
-  - [Small, Focused Source Changes](#-small-focused-source-changes)
-  - [Typing Improvements](#-typing-improvements)
-  - [Refactors of Existing Examples](#-refactors-of-existing-examples)
-  - [Documentation Improvements](#-documentation-improvements)
-  - [Print and Output Clarity](#️-print-and-output-clarity-examples-only)
-  - [Functional Improvements to Examples](#️-functional-improvements-to-examples)
-  - [Test Improvements](#-test-improvements-additive-only)
-- [What We Do NOT Consider Good First Issues](#-what-we-do-not-consider-good-first-issues)
+- [What We Consider Good First Issues](#what-we-consider-good-first-issues)
+  - [Small, Focused Source Changes](#small-focused-source-changes)
+  - [Typing Improvements](#typing-improvements)
+  - [Refactors of Existing Examples](#refactors-of-existing-examples)
+  - [Documentation Improvements](#documentation-improvements)
+  - [Print and Output Clarity](#print-and-output-clarity-examples-only)
+  - [Functional Improvements to Examples](#functional-improvements-to-examples)
+  - [Test Improvements](#test-improvements)
+- [What Is NOT a Good First Issue](#-summary-what-is-not-a-good-first-issue)
 - [Maintainer Guidance](#-maintainer-guidance)
+- [Additional Resources](#additional-resources)
+
 
 ---
 
 ## Purpose
 
 The goal of a Good First Issue is to:
 
-- **Help new contributors get onboarded successfully** — providing a clear, achievable starting point
-- **Build confidence with a meaningful but low-risk contribution** — ensuring success without overwhelming complexity
-- **Reduce maintainer overhead during first-time contributions** — making review and guidance straightforward
+- ✅ **Help new contributors get onboarded successfully** by providing a clear, achievable starting point.
+
+Good First Issues are often a contributor’s **first interaction with open source** and are intended to help them learn our workflow with confidence.
+
+
+## What We Consider Good First Issues
 
-These issues are intentionally:
+Good First Issues are intentionally:
 
 - ✅ Small
 - ✅ Low risk
 - ✅ Easy to review
 - ✅ Safe for first-time contributors
 
----
-
-## Allowed Categories
-
-### 🧵 Small, Focused Source Changes
+Importantly, they have:
 
-Limited, localized changes to existing source files that do not alter public behavior or SDK contracts.
+- ✅ A **very clear, explicitly described, or provided solution**
+- ✅ **No requirement to interpret code behavior or make design decisions**
 
-#### Allowed
-
-- Adding or improving simple string helper functions
-- Implementing or improving `__str__` or `__repr__` methods
-- Fixing or clarifying edge cases in existing utility functions
-
-#### Examples
-
-- Improve formatting of a `__repr__` output
-- Make a string helper more robust or readable
-- Clarify handling of empty or `None` inputs in a utility function
+Below are examples that we consider good first issues:
 
 ---
+### Small, Focused Source Changes
 
-### 🧩 Typing Improvements
+> ⚠️ **Note:** In most cases, changes to `src` functionality are **not** Good First Issues.  
+> This category applies only when the change is **purely mechanical and fully specified**.
 
-Improvements to type annotations that increase correctness or clarity without changing runtime behavior.
+#### Allowed (rare, explicit cases only)
 
-#### Allowed
-
-- Adding missing return type hints
-- Fixing incorrect or overly broad type annotations
-- Resolving basic type conflicts flagged by type checkers
+- Very small, explicitly described edits to existing code
+- Changes that do **not** require understanding how the code is used elsewhere
 
-#### Examples
+#### Not Allowed
 
-- Change `-> Any` to a more specific return type
-- Fix mismatched return types in conditional branches
-- Tighten a `Dict[str, Any]` to a more precise type
+- Any change that requires deciding *how* something should behave
+- Any change that affects public behavior or SDK contracts
 
 ---
 
-### 🔄 Refactors of Existing Examples
+### Typing Improvements
 
-Refactors that improve clarity, structure, or readability of **existing examples only**.
+Typing changes must be **fully specified** and **mechanical**.
 
 #### Allowed
 
-- Refactoring an example for clarity or readability
-- Extracting repeated logic into helper functions
-- Renaming variables to be more descriptive
-
-#### Allowed Directions
+- Adding missing return type hints **when the expected type is explicitly stated**
+- Fixing incorrect or overly broad type annotations **when the correct type is provided**
 
-- Split a large example into smaller, named functions
-- Combine a split example back into a single monolithic function for simplicity
+#### Not Allowed
 
-> ⚠️ **Note:** This category applies **only** to existing examples.  
-> Creating new examples is **out of scope** for GFIs.
+- Inferring correct types by interpreting code
+- Large or cross-file typing refactors
+- Resolving complex type-system issues
 
 ---
 
-### 📚 Documentation Improvements
+### Documentation Improvements
 
-Improvements to documentation that clarify intent or behavior without changing functionality.
-
-#### Includes
-
-- Module-level docstrings
-- Function and method docstrings
-- Inline comments that explain *why* (not what) code does something
-
-#### Examples
-
-- Clarify a confusing or outdated docstring
-- Add explanation for non-obvious behavior
-- Improve wording or structure for readability
-
----
-
-### 🖨️ Print and Output Clarity (Examples Only)
-
-Improvements to output clarity in example code.
+Documentation tasks must be **explicitly scoped** and **instruction-driven**.
 
 #### Allowed
 
-- Improving clarity of `print()` statements
-- Making output more descriptive or user-friendly
-- Standardizing message formatting (prefixes, spacing, context)
+- Remaing variable names when new names are provided
+- Fixing identified typos or grammar issues
+- Making explicitly provided changes to docstrings, comments or print statements
+- Splitting a large example into smaller functions
+- Combining a split example into a single function
 
-#### Examples
+#### Not Allowed
 
-- Replace ambiguous prints like `"Done"` with meaningful context
-- Add explanatory text before printing values
-- Make output ordering easier to follow
+- Writing new documentation
+- Adding docstrings or comments that require interpreting code behavior
+- Deciding *what* should be documented or printed
+- Deciding which steps should exist
 
 ---
 
-### ⚙️ Functional Improvements to Examples
-
-Small functional improvements that better illustrate **existing behavior** in examples.
-
-#### Allowed
-
-- Adding missing steps that improve understanding
-- Improving ordering or structure of example code
-- Clarifying error-handling paths
+### Test Improvements
 
-#### Examples
+> ⚠️ Most test-related work belongs in **Beginner or Intermediate Issues**.
 
-- Add an explicit setup step that was previously implied
-- Improve error-handling clarity in an example
-- Make control flow easier to follow
+#### Allowed (rare, explicit cases only)
 
----
+- Adding a clearly specified assertion to an existing test
+- Small mechanical edits with no test-design decisions
 
-### 🧪 Test Improvements (Additive Only)
-
-Small, additive improvements to **existing** tests.
-
-#### Allowed
-
-- Adding specific assertions to existing tests
-- Extending tests to cover an obvious edge case
-- Improving test names or failure messages
-
-#### Examples
-
-- Add an assertion for a previously untested branch
-- Improve test failure messages for clarity
-
-> ⚠️ Tests must extend **existing test files**.  
-> Creating new test suites or frameworks is **out of scope**.
-
----
-
-## 🚫 What We Do NOT Consider Good First Issues
-
-The following types of changes are **explicitly out of scope** for GFIs.
-
----
-
-### ❌ New Examples
-
-- Creating entirely new examples
-- Adding new example files or workflows
-
-These require deeper understanding of intended usage patterns.
-
----
-
-### ❌ New Unit or Integration Tests
+#### Not Allowed
 
 - Creating new test files
-- Designing new test strategies or frameworks
-
-Test creation often requires broader architectural context.
+- Designing new test cases
+- Extending coverage based on interpretation
 
 ---
 
-### ❌ Core DLT or Protocol Logic
+## 🚫 Summary: What Is NOT a Good First Issue
 
-- Changes to `to_proto` / `from_proto`
-- Modifying serialization or deserialization logic
-- Any change affecting network or wire-level behavior
-
-These areas are sensitive and require domain expertise.
+- ❌ Issues without a clearly defined or provided solution
+- ❌ Tasks requiring interpretation, investigation, or initiative
+- ❌ Changes to `src` functionality that affect behavior
+- ❌ Creating new examples, tests, or documentation
+- ❌ Work spanning multiple files or subsystems
 
 ---
 
-### ❌ Cross-Cutting or Architectural Changes
-
-- Refactors spanning multiple modules or packages
-- Changes requiring understanding of multiple subsystems
-- Performance optimizations or concurrency changes
+### Rule of Thumb
 
-These are better suited for experienced contributors.
+> If a contributor must **decide what to do**,  
+> it is **not** a Good First Issue.
 
 ---
 
 ## 📌 Maintainer Guidance
 
-When evaluating whether to label an issue as a Good First Issue, consider:
-
 ### Label as GFI if the issue:
 
 - ✅ Touches a **single file or module**
 - ✅ Has **clear, well-defined scope**
 - ✅ Requires **no domain or protocol knowledge**
 - ✅ Can be **reviewed quickly**
 - ✅ Has **low risk of breaking changes**
+- ✅ Has a **clear step-by-step solution**
 
 ### Do NOT label as GFI if the issue:
 
@@ -230,13 +153,19 @@ When evaluating whether to label an issue as a Good First Issue, consider:
 - ❌ Requires **domain or protocol knowledge**
 - ❌ Could have **unintended side effects**
 - ❌ Needs **extensive review or testing**
+- ❌ Requires initiative or interpretation to solve
+
+Instead, these are better suited as **Beginner Issues**.
+
+---
 
 ### Important Reminders
 
-1. **Good First Issues are promoted automatically** by GitHub and Hiero, making them highly visible to new contributors
-2. **Quality over quantity** — we prefer fewer, clearly safe GFIs over many ambiguous ones
-3. **Clear acceptance criteria** — every GFI should have well-defined success conditions
-4. **Link to documentation** — include relevant guides to help contributors succeed
+1. **Good First Issues are promoted automatically** by GitHub and Hiero, making them highly visible
+2. **Good First Issues are self-assigned** (via `/assign`), so they must be achievable by anyone
+3. **Quality over quantity** — prefer fewer, clearly safe GFIs
+4. **Clear acceptance criteria** — every GFI should define what “done” means
+5. **Link to documentation** — include relevant guides to help contributors succeed
 
 ---