Skip to content

docs: add GSD comparison section to README#203

Open
gx-ai-architect wants to merge 2 commits into
mainfrom
docs/gsd-comparison
Open

docs: add GSD comparison section to README#203
gx-ai-architect wants to merge 2 commits into
mainfrom
docs/gsd-comparison

Conversation

@gx-ai-architect
Copy link
Copy Markdown
Collaborator

Summary

  • Adds a "How It Compares to GSD" section to the README, positioned after "Built with the Factory"
  • Highlights three key differentiators: single-command workflow, self-verification that works, and high-level steering
  • Tone is respectful — acknowledges GSD as a great tool, focuses on Factory strengths rather than GSD weaknesses

Test plan

  • Verify README renders correctly on GitHub
  • Confirm GSD repo link resolves

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@codecov
Copy link
Copy Markdown

codecov Bot commented May 8, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.20%. Comparing base (f72f5e6) to head (de3ee0c).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main     #203      +/-   ##
==========================================
+ Coverage   86.97%   87.20%   +0.23%     
==========================================
  Files          51       52       +1     
  Lines        7276     7440     +164     
==========================================
+ Hits         6328     6488     +160     
- Misses        948      952       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link
Copy Markdown
Owner

@akashgit akashgit left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review

Tone risk. The comparison reads as marketing copy — "self-verification that works" implies GSD's doesn't, and "GSD often punts things to the human that it could check itself" is dismissive of another open-source project. For a repo README this creates unnecessary friction and invites a flame war rather than collaboration.

Placement. This is wedged between "Built with the Factory" and "Live Dashboard" — two factual sections. A subjective comparison breaks the flow.

Recommendation: I'd suggest not merging this as-is. Competitive comparison sections in READMEs tend to age poorly, invite rebuttals, and aren't the right venue. If you want this content, a blog post or a docs/comparisons.md would be better suited. The claims also need evidence (benchmarks, concrete examples) rather than bare assertions.

Move from standalone comparison section to a short motivation
paragraph at the top. Softer tone, focuses on why the Factory
exists rather than what's wrong with alternatives.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@gx-ai-architect
Copy link
Copy Markdown
Collaborator Author

Thanks for the review! Addressed all three points in de3ee0c:

  • Tone: Removed the standalone comparison section entirely. Replaced with a two-sentence "Why we built this" motivation paragraph — acknowledges GSD as powerful, no dismissive language.
  • Placement: Moved from between "Built with the Factory" / "Live Dashboard" to right under the intro tagline, where motivation naturally belongs.
  • Format: No longer a comparison section — it's a brief motivation for why the project exists. No assertions that need evidence, just "we wanted less manual steps and better self-verification."

The full diff is now +2/-10 from the original.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants