Pilot moderated discussions on Insights and project pages

Classification: Website Improvement
Recommendation: APPROVED WITH IMPROVEMENTS
Priority: P2 / evidence-gathering pilot

Problem

Insights and project case studies currently publish one-way engineering evidence. A bounded discussion surface could let readers ask useful technical questions, challenge decisions, and add durable context. However, a custom comment platform would introduce authentication, authorization, storage, abuse prevention, privacy, accessibility, moderation, deletion, and operational obligations that conflict with the site's intentionally static, low-maintenance architecture.

Decision direction

Pilot GitHub Discussions-backed comments, preferably through a progressively enhanced integration such as Giscus, rather than building a custom account/comment database.

The desired user capability is:

• authenticated readers can add comments;
• a comment author can edit or delete their own comments through GitHub;
• Mantosh can moderate, hide/delete, lock, or restrict discussions;
• unauthenticated visitors can read without being forced to sign in;
• commenting remains optional and does not obstruct the article/project content.

Do not implement anonymous unrestricted comments.

Brand and product boundary

The discussion surface must strengthen engineering credibility, not optimize for generic engagement.

Allowed discussion:

• technical questions about the published work;
• alternative designs and trade-offs;
• corrections and evidence-backed challenges;
• implementation and operational lessons.

The feature must not:

• turn Ask Mantosh into a general social/chat system;
• treat visitor comments as verified claims or authoritative portfolio evidence;
• ingest comments into Ask Mantosh, knowledge/, résumé evidence, SEO metadata, RSS, or article content automatically;
• expose private employer or visitor information;
• add visible empty-state clutter to every page before the pilot proves value.

Pilot scope

1. Confirm GitHub Discussions is enabled and select/create a dedicated category.
2. Map each canonical pilot page to exactly one Discussion using a stable page identifier.
3. Pilot on:
   • one substantive Insight;
   • one public project case study.
4. Load the discussion UI progressively near the end of the page or after a visitor activates “Join the discussion.”
5. Match all supported site themes, including High contrast.
6. Publish concise moderation and privacy expectations.
7. Run the pilot long enough to determine whether discussion quality justifies broader rollout.
8. Expand to all Insights/projects only after an explicit readback decision.

Functional requirements

• Signed-in GitHub users can create a comment.
• Comment authors can edit and delete their own comments using GitHub's ownership controls.
• Mantosh can moderate and lock the underlying Discussion.
• Each canonical page maps deterministically to one Discussion with no duplicates after URL/title changes.
• Comments remain readable when supported, while sign-in is required only to participate.
• The main article/project remains fully usable when GitHub/Giscus is blocked or unavailable.
• No comment content is copied into repository evidence or Ask Mantosh automatically.
• Deleted/hidden comments do not remain cached by site-owned infrastructure.

Non-functional requirements

Security, privacy, and abuse

• Document the third-party GitHub dependency and authentication boundary.
• Review CSP/referrer/iframe changes explicitly; allow only the minimum required origins.
• No custom access token or GitHub credential reaches the browser.
• Use GitHub moderation, repository interaction limits, locking, and reporting controls.
• Define a response for spam, harassment, private data, and unsupported employer claims.
• Do not display raw email addresses or create an anonymous posting path.

Accessibility and performance

• Keyboard and screen-reader flows work for loading, reading, signing in, and recovering from failure.
• Light, Dark, Soft, Auto, and High contrast presentations remain readable.
• Comments do not cause disruptive layout movement.
• Lazy/progressive loading preserves current page and JavaScript budgets.
• A third-party failure produces a small fallback link to the canonical Discussion.

Deterministic verification

• Tests prove stable page→Discussion mapping and prevent duplicate discussion creation.
• Browser tests cover successful load, unavailable/blocked third-party fallback, theme synchronization, and keyboard navigation.
• Existing npm run verify, browser checks, accessibility audits, link audits, CSP checks, and performance budgets remain green.
• Documentation and docs/SYSTEM_STATE.md distinguish the pilot from a completed site-wide rollout.

Pilot success criteria

Expand beyond the two pilot pages only if:

• discussion contains substantive engineering questions or corrections;
• moderation load remains low;
• no material accessibility, privacy, performance, or spam problem appears;
• the surface makes an Engineering Manager or Staff/Principal Engineer more confident in Mantosh's judgment or communication.

If the pilot is empty, noisy, or maintenance-heavy, remove the embed and retain a simple “Discuss on GitHub” link instead.

Out of scope

• custom registration/login;
• anonymous comments;
• custom comment database/API;
• reactions, reputation points, follower systems, notifications, or engagement feeds;
• automatic publication of comments as portfolio evidence;
• changes to Ask Mantosh's evidence boundary.

Traceability

This issue records the 2026-08-22 founder proposal to allow readers to add, edit, and delete comments on Insights and project pages. Repository instructions, VISION.md, and docs/SYSTEM_STATE.md require the low-maintenance, evidence-first pilot shape above.