Skip to content

Clean the public docs for strangers - #18

Merged
scottwb merged 1 commit into
mainfrom
docs/public-cleanup
Oct 28, 2026
Merged

scottwb merged 1 commit into
mainfrom
docs/public-cleanup

Conversation

@scottwb

@scottwb scottwb commented Oct 28, 2026

Copy link
Copy Markdown
Member

Docs only. No code or behavior change, no history rewrite. Offline suite: 512 passed. All internal links and anchors resolve.

1. Internal-only references

  • Roadmap: removed the owner quote, the DM screenshots and contractor time-log motivation, the names of other organizations' workspaces and their refusal message, and live-workspace sizes (now generic wording).
  • CLAUDE.md: the merge guidance no longer names personal workflow commands.
  • Architecture and PRD: "the live workspace" and "the author's workspace" now read "a real workspace".

2. Stale PR numbers and commit ranges

  • Deleted docs/assessments/ (three phase-gate audits) and five finished plans (slackline-read-mvp, read-only-mvp-gate-fixes, gate-rerun-fixes, public-release-prep, slackline-skill). They cited pre-release PRs and commits that are not in this repository's history. Git keeps them.
  • Roadmap Completed section rewritten shorter, with no PR numbers, commit hashes, branch names, or links to the deleted files.
  • Phase 2.0 plan: Seed-N now cites the numbered seed list in the roadmap, and its PR references are reworded.

3. Contradictions

  • Roadmap now matches the code: in text and JSONL a file appears as a rendered [file: name (type, size)] line in the message text, nothing dropped, but no structured file metadata and no download.
  • README "What is not built yet" now lists downloading attachments.

4. Stale wording

  • README status: v0.2 to v0.2.2, and "a real workspace".
  • pyproject.toml comment: "One executable in v0.1" to "One executable today".
  • Roadmap Phase 3.1: publication is done; only the PyPI name is undecided. The finished pre-publication checklist is removed.
  • README whoami sample: kept as printed (it matches real output), plus a note that the manifest does not request identify; Slack grants it to every user token.
  • Seed 3 (trim the roadmap follow-ups bullet) is done here and checked off in the Phase 2.0 plan.

Checked and kept

  • The "App Token" wording in quick start step 2: it comes from a tested walkthrough of Slack's current screens.
  • Anonymized measurements in the architecture and PRD (for example, 18% of sampled messages have no text, and duplicate group DM names): they are the evidence behind design decisions, and every name in them is already a stand-in.
  • The owner's name in the PRD header and the author entry in pyproject.toml.

The repository went public with docs written for its own development.
Before anyone is pointed at it, they should read clean to someone who
was not there.

Internal material is gone: owner quotes, the private files that
motivated the attachments feature, other organizations' workspaces,
live-workspace sizes, and personal workflow command names.

The three phase-gate audits and five finished plans are deleted. They
cited PR numbers and commit hashes from the pre-release repository,
which now point at unrelated public PRs or at nothing. The roadmap's
Completed section carries what they delivered, without those
references, and git keeps the files.

Contradictions and stale wording are fixed: the roadmap claimed JSONL
drops the files array, when it carries the rendered file line and no
structured metadata; the README status said v0.2; pyproject said
v0.1; Phase 3.1 still waited on a publication decision already made;
and the Phase 2.0 plan cited seeds from a deleted audit, now numbered
in the roadmap. The README notes why whoami lists identify and adds
attachment download to what is not built yet.
@scottwb
scottwb merged commit b7bdf86 into main Oct 28, 2026
2 checks passed
@scottwb
scottwb deleted the docs/public-cleanup branch October 28, 2026 01:59
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.

1 participant