@cryptotaxi247 / SquadScope / commits / aa44952

Publish methodology and correction path

Adds reader-facing methodology, correction-report links, and distribution guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Juan Manuel Servera committed Jun 7, 2026 at 10:49 UTC aa449525d9465a1639afebbe8ff2222ae22ec4fc
5 files changed +95 -3
assets/css/extended/squadscope.css
+20
@@ -465,6 +465,7 @@ summary:focus-visible,
465 .article-footer__prompt,
466 .article-footer__updated,
467 .article-errata,
468 +.article-correction-path,
469 .repo-card__stats {
470 color: var(--color-text-muted);
471 font-size: var(--text-sm);
@@ -720,6 +721,25 @@ summary:focus-visible,
721 font-style: italic;
722 }
723
724 +.article-correction-path {
725 + display: grid;
726 + gap: var(--space-2);
727 + padding: var(--space-3);
728 + border: var(--size-border-thin) solid var(--color-border);
729 + border-radius: var(--radius-md);
730 + background: var(--color-surface);
731 +}
732 +
733 +.article-correction-path__title {
734 + margin: 0;
735 + color: var(--color-text);
736 + font-size: var(--text-base);
737 +}
738 +
739 +.article-correction-path p {
740 + margin: 0;
741 +}
742 +
743 .article-errata__title {
744 margin: 0;
745 color: var(--color-text);
content/methodology/_index.md
+19 -2
@@ -26,18 +26,35 @@ For topic channels, `scripts/score_repos.py` can compute a 0-100 relevance score
26
27 `signals.json` is not a separate source; in the current payload, `signals` is the structured summary generated from crawled repositories. `scripts/momentum_tracker.py` adds a hindsight check for press-correlated repos: after two or four weeks, a repo is marked sustained if its later stars gained are at least 20% of the initial gain; otherwise it is marked faded. The recorded decay rate is `1 - current / initial`, clamped between 0 and 1.
28
29 -## Biases readers should account for
29 +## Responsible-AI caveats and bias limits
30
31 +- **Source bias:** GitHub repositories and the current TechCrunch feed are only a slice of developer activity. Private work, enterprise pilots, package registries, community forums, regional press, and smaller newsletters are under-observed, so SquadScope should not be read as a neutral or complete map of technology.
32 - **English-language source bias:** GitHub metadata and the current TechCrunch feed favor English-language projects and coverage; treat non-English ecosystem absence as under-observation, not lack of activity.
33 +- **Platform bias:** GitHub-centric measurement over-represents open-source projects, public launch behavior, star-seeking promotion, and communities that already use GitHub. Work happening on GitLab, SourceHut, Bitbucket, self-hosted forges, package registries, Discord, Slack, or behind company firewalls may be invisible.
34 - **High-star bias:** The default crawl requires more than 50 stars and sorts by stars, so important niche projects can be missed until they are already visible.
35 - **US and Bay Area press bias:** TechCrunch coverage reflects a US startup lens; read press correlation as one narrative input, not a global technology map.
36 - **BigCo signal-strength bias:** Large companies create more repos, launches, docs, and articles, so their activity can look more important than quieter independent work.
37 - **Survivorship bias:** We mostly see projects that remain public and crawlable; failed experiments, abandoned private work, and deleted repos are largely invisible.
38 - **Recency bias:** A weekly window is good at catching spikes but can miss slower ecosystem shifts; use monthly and yearly rollups for longer arcs.
39
40 +These caveats are part of the analysis, not a disclaimer that makes the output neutral. The AI-assisted write-up can still over-weight vivid examples, repeat gaps in source coverage, or describe a project more confidently than the evidence supports. Reader reports are welcome when a claim, framing, source choice, or safety implication needs review.
41 +
42 +## Corrections and reader reports
43 +
44 +Weekly articles include a footer link to report a correction, source concern, or safety concern through GitHub Issues. The link prefills the article URL and week so reports can be triaged against the exact published page.
45 +
46 +When a report arrives, maintainers should:
47 +
48 +1. **Triage the report.** Confirm the affected article/week, classify it as factual correction, source-quality issue, safety concern, bias/framing concern, or duplicate/out of scope, and ask for additional evidence only if the report cannot be evaluated from public sources.
49 +2. **Update carefully.** Preserve the article's original publication context where possible. Fix clear factual errors, broken links, unsafe framing, or materially misleading source descriptions in the content or template that caused them.
50 +3. **Leave visible correction notes.** For material changes, add an `errata` entry to the weekly article front matter with the correction date and a concise note. Minor typo/link fixes may be corrected without an errata note, but source, safety, ranking, or claim changes should be visible to readers.
51 +4. **Close the loop.** Reply on the GitHub issue with what changed, what was not changed, and why. If the concern reveals a process gap, update this methodology or the relevant pipeline documentation.
52 +
53 +Correction reports are not used to provide private support, remove criticism without evidence, or retroactively make every old article match the latest methodology. They are a path for readers to challenge evidence, improve safety, and make material updates visible.
54 +
55 ## What we do not do
56
40 -We do not sell paid placements, accept sponsor influence over selection, or reserve ranking slots for partners. Editorial articles are AI-generated from collected signals; see the site footer disclosure and [About](/about/) page for that operating model. We do not retroactively rewrite past articles after publication. Until the dedicated errata process from issue #209 lands, corrections and concerns should be raised through [GitHub issues](https://github.com/jmservera/SquadScope/issues/new).
57 +We do not sell paid placements, accept sponsor influence over selection, or reserve ranking slots for partners. Editorial articles are AI-generated from collected signals; see the site footer disclosure and [About](/about/) page for that operating model. We do not silently retroactively rewrite past articles after publication. Corrections and concerns should be raised through [GitHub issues](https://github.com/jmservera/SquadScope/issues/new?labels=correction%2Creader-report).
58
59 ## Future work
60
docs/growth/distribution-strategy.md
+2 -1
@@ -212,6 +212,8 @@ campaign the crawl has caught.
212
213 **Input:** `content/weekly/2026/W22.md` (published Monday 8:30 AM UTC)
214
215 +**Before promotion:** Read the public [Methodology and corrections policy](../../content/methodology/_index.md) and link the live methodology page (`https://jmservera.github.io/SquadScope/methodology/`) in launch/crosspost context when space allows. Do not promote an article as neutral or comprehensive; frame it as GitHub- and current-source-based analysis with known source, language, and platform limits.
216 +
217 **Step 1: Extract key angles** (5 min)
218 - Skim article for 3-5 "most quotable" sections
219 - Identify 1-2 thread hooks (what's surprising, what's missing)
@@ -553,4 +555,3 @@ Before GA4, log weekly:
555 - Evaluate whether newsletter should move off Buttondown (if >1K subscribers)
556 - Explore paid distribution options (if metrics justify)
557 - Build SquadScope brand presence on all key platforms
556 -
layouts/partials/article-footer.html
+14
@@ -2,6 +2,11 @@
2 <footer class="post-footer article-footer">
3 {{- $tags := $page.Language.Params.Taxonomies.tag | default "tags" -}}
4 {{- $categories := $page.Language.Params.Taxonomies.category | default "categories" -}}
5 + {{- $week := $page.Params.week | default $page.Title -}}
6 + {{- $articleURL := $page.Permalink -}}
7 + {{- $issueTitle := printf "Correction report: %s" $week -}}
8 + {{- $issueBody := printf "## Correction / source / safety concern\n\nArticle: %s\nWeek: %s\n\nConcern type: correction / source concern / safety concern\nSuggested labels for maintainers: correction, source concern, safety concern, or bias/framing concern\n\nWhat should be corrected or reviewed?\n\n\nSuggested source(s) or evidence:\n\n\nVisible correction note needed? yes/no\n" $articleURL $week -}}
9 + {{- $reportURL := printf "https://github.com/jmservera/SquadScope/issues/new?title=%s&body=%s&labels=%s" ($issueTitle | urlquery) ($issueBody | urlquery) ("correction,reader-report" | urlquery) -}}
10 <div class="article-footer__taxonomies" aria-label="Report taxonomy">
11 <ul class="post-tags">
12 {{- range ($page.GetTerms $categories) }}
@@ -34,6 +39,15 @@
39 <a href="mailto:?subject={{ $page.Title | urlquery }}&amp;body={{ $page.Permalink | urlquery }}">Share this report</a>
40 </div>
41
42 + <section class="article-correction-path" aria-labelledby="article-correction-path-title">
43 + <h2 id="article-correction-path-title" class="article-correction-path__title">Methodology and corrections</h2>
44 + <p>
45 + Read the <a href="{{ "methodology/" | absURL }}">methodology and correction policy</a>,
46 + or <a href="{{ $reportURL | safeURL }}">report a correction, source concern, or safety concern</a>.
47 + The report link prefills this article URL and week.
48 + </p>
49 + </section>
50 +
51 <p class="article-footer__updated">Last updated <time datetime="{{ $page.Lastmod.Format "2006-01-02T15:04:05Z07:00" }}">{{ $page.Lastmod.Format "Jan 2, 2006" }}</time></p>
52
53 {{- with $page.Params.errata }}
tests/test_site_policy_links.py new
+40
@@ -0,0 +1,40 @@
1 +from pathlib import Path
2 +
3 +
4 +ROOT = Path(__file__).resolve().parents[1]
5 +
6 +
7 +def test_weekly_article_footer_has_prefilled_correction_report_link() -> None:
8 + footer = (ROOT / "layouts/partials/article-footer.html").read_text(encoding="utf-8")
9 +
10 + assert "Correction report: %s" in footer
11 + assert "Article: %s" in footer
12 + assert "Week: %s" in footer
13 + assert "issues/new?title=%s&body=%s&labels=%s" in footer
14 + assert "correction,reader-report" in footer
15 + assert "Suggested labels for maintainers" in footer
16 + assert "report a correction, source concern, or safety concern" in footer
17 +
18 +
19 +def test_methodology_page_documents_corrections_and_responsible_ai_limits() -> None:
20 + methodology = (ROOT / "content/methodology/_index.md").read_text(encoding="utf-8")
21 +
22 + assert "## Responsible-AI caveats and bias limits" in methodology
23 + assert "**Source bias:**" in methodology
24 + assert "**English-language source bias:**" in methodology
25 + assert "**Platform bias:**" in methodology
26 + assert "not be read as a neutral or complete map" in methodology
27 + assert "## Corrections and reader reports" in methodology
28 + assert "Leave visible correction notes" in methodology
29 + assert "`errata` entry" in methodology
30 +
31 +
32 +def test_methodology_is_in_navigation_and_distribution_guidance() -> None:
33 + hugo_config = (ROOT / "hugo.toml").read_text(encoding="utf-8")
34 + distribution = (ROOT / "docs/growth/distribution-strategy.md").read_text(encoding="utf-8")
35 +
36 + assert "identifier = 'methodology'" in hugo_config
37 + assert "url = '/methodology/'" in hugo_config
38 + assert "Methodology and corrections policy" in distribution
39 + assert "https://jmservera.github.io/SquadScope/methodology/" in distribution
40 + assert "Do not promote an article as neutral or comprehensive" in distribution