docs(contributing): structure spec with H1 and front matter

[zolotokrylin]

• Closes Problem: wrong semantic in spec format #111

Summary by CodeRabbit

• Documentation
  • Revised contribution guidelines with clearer problem definitions, updated specification format guidance, and streamlined PR requirements. Enhanced instructions for commit signatures, PR scoping rules, issue/PR referencing, and review processes to provide better clarity for contributors.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
zolotokrylin	✅ Submitted	15min	Update time	May 4, 2026, 5:04 PM
angelicawill	✅ Submitted	10min	Update time	May 4, 2026, 5:05 PM

---

You can submit time with the command. Example:

@holdex pr submit-time 15m

See available commands to help comply with our Guidelines.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fc07d6b1-c391-47f5-848d-5840ee02ed25

📥 Commits

Reviewing files that changed from the base of the PR and between c0c4dc3 and 4185d63.

📒 Files selected for processing (1)

• docs/CONTRIBUTING.md

---

Walkthrough

This PR revises docs/CONTRIBUTING.md to streamline contribution guidance across multiple sections: Problem definition, Specs format, communication instructions, PR requirements, commit verification, scoping rules, naming phrasing, and review processes. Changes reword for clarity, condense length, and introduce a front-matter style for Spec metadata.

Changes

Contribution Guidelines Documentation

Layer / File(s)	Summary
Problem & Solution Definitions docs/CONTRIBUTING.md (lines 30, 57–58, 89–90)	Reworded "Problem" to concise barrier-based definition; removed the "Different problems may require different sets of skills" line from Solution section.
Specs Guidance & Format docs/CONTRIBUTING.md (lines 104–107, 135–140)	Clarified Spec scope as a markdown file in docs/specs/; moved Google Docs references to Goal issues only; changed format from italic _Goal:_ plus optional "Ideation" to goal: <link> front-matter followed by # Feature Name H1.
Communication & PR Lifecycle Rules docs/CONTRIBUTING.md (lines 165–166, 213–214, 232–233, 253–254)	Updated communication to "direct discussions to the appropriate channel"; added explicit warning callout for PR rejection on non-compliance; condensed commit signature verification to single directive; added 24-hour activity rule with explanation requirement.
Referencing, Naming & Review Guidance docs/CONTRIBUTING.md (lines 190–191, 286–288, 381–387)	Tightened referencing rationale to GitHub list rendering behavior; simplified naming guidance to "Ask what users can do, not what am I building"; rewrote Scout Approach and Code Quality instructions for directness and brevity.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

• docs(contributing): attach Google Doc to Goal, not to Spec #110: Updates Spec template format and relocates Google Doc references from Spec to Goal issue, directly overlapping on front-matter and metadata handling.
• docs(contributing): follow spec lifecycle for goals #108: Modifies Specs section guidance and clarifies spec workflow requirements, addressing the same documentation section.
• docs: see PR review guidelines #74: Rewrites PR review guidance (Scout Approach and Code Quality sections), covering overlapping content with this PR.

Suggested reviewers

• markholdex
• angelicawill

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes substantial additional changes beyond the H1/front-matter fix, such as reworded problem definitions, adjusted specs guidance, communication updates, and condensed formatting—extending beyond the linked issue's scope.	Isolate the H1 and front-matter changes in a focused PR; move other documentation improvements (problem rewording, specs guidance adjustments, etc.) to separate PRs for clearer review and intent tracking.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: restructuring the spec format example to include an H1 heading and front matter organization.
Linked Issues check	✅ Passed	The PR implements Option A from issue #111 by adding H1 and front-matter structure to the spec format example, meeting the stated objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/spec-ideation-in-goal

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch docs/spec-ideation-in-goal

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[zolotokrylin]

@holdex pr submit-time 15m

[angelicawill]

@holdex pr submit-time 10m