Skip to content

docs: repository - Remove obsolete portfolio references and docs #448

Open

Description

@ashleyshaw

Documentation Update Summary

Remove obsolete ashshaw.makeup portfolio instructions from the documentation for lightspeedwp/ThisOneTimeOnAcidCom. Rewrite useful inherited guidance for the current book website, and retire irrelevant or duplicated material only after checking references, retained content and provenance.

The saved review covers all prose across 133 files under docs/ at develop revision 6b3b76baa955acdfaee0d5e4aef39e099b4b083e. This is a historical review inventory, not a verified count of remaining work. Twelve embedded images remain unassessed in that review.

Recorded progress

The native issue status changed from Backlog to In Progress on 11 November 2026. The saved review covers develop revision 6b3b76baa955acdfaee0d5e4aef39e099b4b083e; the five consolidated rewrite drafts below use develop revision 3f583002482d80ffd1910676bcf7c63e13989b20.

#481 merged on 25 October 2026 at 01:18:22 UTC. Its bounded contribution comprised eight documentation paths:

  • Edited docs/ebook-preferences.md
  • Edited docs/TESTING.md
  • Edited docs/dark-mode-troubleshooting.md
  • Edited docs/NETLIFY_CACHE_VERIFICATION.md
  • Edited docs/INTEGRATION-VALIDATION-PLAN.md
  • Edited docs/pending-questions.md
  • Deleted docs/figma-ai-brief-1.md
  • Deleted docs/makeup-kit-essentials.md

The branch-strategy inspection verified that PR head 5607ce8077f8cbb5541fc116c69b8b14d065139f is contained in inspected main revision ff9b152f6b57dadb08d672acac9f1690d59988d4, with identical contents at those eight paths. Inspected develop revision e971ff39daf71c25224d2746d71817349dd0dfe2 does not contain that head, retains both deleted files and differs at the six edited paths. Do not replay or backport the contribution without a separately scoped decision.

The PR was independently discovered; the issue’s native Linear pull-request list was empty during inspection. That missing native association does not mean no implementation exists.

This establishes the merged eight-file contribution, not completion of the wider documentation review, satisfaction of every criterion, deployment or publication. The remaining review inventory and dispositions require reconciliation against the selected current baseline.

Linked Stories/Tasks/PRs/Epic

Coordinate with #416 on book/site instructions and workflows, #266 on documentation structure, and #408 on root guidance and tooling.

These three issues are linked through existing native related relationships. No parent or closing association is recorded, and no relationship changes are proposed.

#481 provides the completed eight-file contribution described above. Its reference to GitHub #448 is non-closing; wider issue completion remains a separate decision. This description does not add a native development or closing association.

Milestones & Timeline

The issue is assigned to Builds & CI reliable. No release commitment or deadline is specified.

What documentation is needed?

Use the attached review to agree file-level retain, rewrite, retire or delete decisions. Reconcile those decisions with the merged eight-file contribution before identifying further changes; do not treat the original inventory as wholly outstanding.

Prioritise:

  • Obsolete portfolio, Nova News and foreign-repository instructions.
  • Duplicate book briefs.
  • Current routes, ebook preferences, testing/setup and safe troubleshooting guidance.
  • Historical completion reports and speculative developer-tool or WordPress plans presented as current requirements.
  • Separation of approved public copy, editorial research and restricted notes.

Do not remove genuine author history, useful research or attribution merely because it mentions makeup, music, festivals or the original website.

Why is this documentation important?

Inherited instructions conflict with the current book-first website and can misdirect contributors into retired features, unsafe maintenance commands or unapproved migrations.

Acceptance Criteria

  • Documentation is clear, accurate, and up-to-date
  • Includes code examples/screenshots if applicable
  • Documentation is accessible and easy to find
  • Changelog entry prepared for PR if user-facing update
  • PR uses correct branch prefix (docs/)
  • PR description updated with relevant details
  • Changelog entry prepared for PR (if applicable)
  • Labels/types match org standards
  • All 133 files have an approved disposition; mixed-purpose files identify retained sections
  • The 12 embedded images are assessed or explicitly excluded before asset-affecting decisions
  • Approved moves/deletions preserve attribution and retained material, with inbound references checked and updated
  • Current guidance matches verified routes, paths, reader-preference contracts and available commands
  • Historical reports and proposals are distinguished from current requirements, executed checks and approval
  • No blanket domain/name replacement, reader-storage-key changes, manuscript deletion or publication of restricted notes
  • Changes remain documentation-only; application, dependencies, hosting, deployment and shared governance remain unchanged
  • Validation records actual results and untested areas
  • Intervening develop changes are reviewed before implementation

Additional Context

Approved deletion scope

  • Delete docs/figma-ai-brief-1.md; retain docs/figma-ai-brief.md as canonical
  • Delete docs/makeup-kit-essentials.md
  • Remove the unrelated résumé image, its definition and associated search-result fragment from docs/pending-questions.md

These recorded deletion choices were implemented by PR #481 and verified at the inspected main revision. They are retained here as historical scope, not instructions to repeat the deletions.

The PR describes its rewrite inputs as owner-approved uploads. This inspection verified the merged contribution, but did not independently reconstruct the historical approval trail or compare every attachment byte-for-byte with the merged files. Do not describe all rewrites as still unimplemented or infer approval for additional changes.

Repository: lightspeedwp/ThisOneTimeOnAcidCom
Reviewed folder: docs at the historical review revision

Report: thisonetimeonacid-docs-review-2026-10-24.md

Pending decisions: canonical book brief; historical-report retention; future WordPress-reference scope; restricted editorial material; documentation-only changelog requirements. Reconcile these recorded decisions with the merged contribution before treating them as remaining implementation work.

Remaining scope and evidence gaps:

  • Reconcile the historical 133-file inventory with the completed contribution and selected current baseline.
  • Establish remaining approved dispositions, including retained sections in mixed-purpose files.
  • Assess or explicitly exclude the twelve images before further asset-affecting decisions.
  • Resolve the authoritative base and material main/develop divergence before planning further implementation.
  • Establish wider acceptance evidence separately from the merged contribution. No criteria or checkbox states are changed by this correction.

No implementation, branch creation, deployment or related-record changes are authorised by issue creation. This correction does not authorise further repository work.


Definition of Ready (DoR)

  • Documentation need is clear and well-defined
  • Related docs/issues or files linked
  • Acceptance criteria listed
  • Estimate added if relevant
  • Milestone/release assigned (if applicable)

Definition of Done (DoD)

  • Documentation meets org standards and guidelines
  • Changelog entry prepared for PR (CHANGELOG.md)
  • Documentation reviewed for clarity and accessibility
  • Screenshots/code examples included if relevant
  • PR uses correct branch prefix (docs/)
  • PR uses the correct PR template based on type:docs PR label or linked issue type or linked issue type:docs label
  • Branch deleted after merge
  • Linked issue(s) updated with latest status and closed after merge,
  • The related epic should not be closed, instead updated with a comment to reflect the closed issue

Branch instructions

The earlier proposed branch was used by merged PR #481. The following distinguishes that historical contribution from unresolved future work; it does not authorise branch creation, reuse or further changes.

  • Repository: lightspeedwp/ThisOneTimeOnAcidCom
  • Historical branch: docs/repository-legacy-cleanup, used by PR docs: repository - Remove obsolete guidance and documents #481; absent from the remote branch list inspected during the branch-strategy assessment
  • Historical PR base: develop
  • Branch state for remaining work: Unresolved; do not recreate or reuse the historical branch automatically
  • Branch for remaining work: Recommendation withheld pending distinct remaining scope and resolution of the base-policy conflict
  • Base for remaining work: Recommendation withheld; inspected main instructions favour main, while local branching guidance and develop instructions favour develop, and the branches differ materially
  • Naming evidence: Target AGENTS.md, CONTRIBUTING.md, docs/BRANCH_NAMING_LOCAL.md, .agents/roles/branches-agent.md and scripts/validate-branch-name.js; docs/ is permitted for documentation changes, but no exact new name has been validated
  • Pull request template: lightspeedwp/.github/.github/PULL_REQUEST_TEMPLATE/pr_docs.md, inspected at organisation revision b63f9bbb0c186f68b0a1cf6cad1b30c89be38f5c; populate explicitly for any separately authorised contribution
  • Implementing issue: docs: repository - Remove obsolete portfolio references and docs #448
  • Parent epic and closing targets: None proposed; a partial contribution does not establish whole-issue completion
  • Expected files for further work: File plan withheld — insufficient evidence for new operations until remaining dispositions and baseline are resolved
  • PR scope: Do not duplicate the merged eight-file contribution or infer permission to backport it
  • Constraints: Preserve protected assets, attribution, restricted editorial material and unrelated changes. No runtime, deployment, dependency or shared-governance changes.
  • Conflicts: Local routing uses type:documentation while shared taxonomy uses type:docs; changelog requirements remain unresolved for future work. Do not repair these as a side effect.
  • Scope-change gate: Obtain approval before expanding files or operations beyond an agreed documentation plan.

Evidence limits

The branch-strategy inspection checked main ff9b152f6b57dadb08d672acac9f1690d59988d4, develop e971ff39daf71c25224d2746d71817349dd0dfe2, PR head 5607ce8077f8cbb5541fc116c69b8b14d065139f, relevant repository instructions, branch validation source, PR metadata and the eight-path comparison.

These are inspected revisions, not a guarantee that branches remain unchanged. No tests or branch validator were executed during that assessment. Attachment contents, all remaining documentation and the twelve images were not reassessed. Merge does not establish deployment, publication or whole-issue acceptance.

WordPress documentation removal proposal — wording-approved candidate

Project direction and approval boundary

On 11 November 2026, Ash confirmed that this project will not undertake WordPress implementation or development and approved the direction of removing documentation prescribing that work.

At 14:48:57 UTC, Ash approved wording only for the six-file candidate comprising the original section-removal preview, revision-2 amendments and stated patch-transcription corrections. That approval does not authorise saving, repository edits, branch creation, implementation, pull requests, deployment or publication.

The exact candidate remains the previously displayed patches and amendments in this conversation. The scope summary below records that candidate; it is not a replacement patch or approval of different wording.

Six-file wording-approved candidate

Inspected repository baseline: lightspeedwp/ThisOneTimeOnAcidCom, main revision ff9b152f6b57dadb08d672acac9f1690d59988d4.

File Wording-approved proposed change Preserved boundary
docs/figma-ai-brief.md Replace WordPress-specific section 27 framing with content-model notes; neutralise follow-up prompt 4’s WordPress mapping requirement. Canonical book brief, content-model concepts, other prompts and existing section numbering.
docs/cms-field-mapping.md Replace inherited WordPress Purpose metadata; add a qualified reference scope; remove WordPress architecture, backend mappings, deferred integrations, CPT/taxonomy, caching and import instructions. All 78 field/requiredness/type entries, useful inherited notes, provenance, version and date. Remaining paths and model details are not represented as revalidated current contracts.
docs/template-parts-specification.md Remove the headless WordPress architecture assertion. Generic layout/component concepts, variants and existing metadata. Its historical APPROVED label is not fresh acceptance evidence.
docs/css-guidelines.md Remove WordPress alignment requirements and proposed WordPress directory; distinguish retained source attribution from implementation guidance. Generic styling/token guidance and source citations. Unrelated company-wide applicability claims are not newly endorsed.
docs/figma-audit-orchestrator.md Remove WordPress compatibility, preset, mapping and implementation requirements; add an external-source attribution boundary. Generic audit concepts and citations. Other foreign-repository instructions remain unresolved and unauthorised for execution.
docs/orchestrator-prompt.md Replace WordPress-specific audit, report and implementation framing with generic token/global-class guidance; remove the proposed WordPress directory; qualify retained bibliography attribution. Useful audit structure, numbering and source attribution. No authority to execute the orchestrator is granted.

Revision 2 preserves WordPress source references where required for attribution while explicitly separating them from implementation requirements.

The approved transcription corrections affect patch representation only, not candidate meaning. No new version numbers or revision dates were assigned.

Later approved whitespace-context corrections

At 2026-11-11T16:24:39.033Z, Ash approved only the seven displayed whitespace-context transcription corrections to the consolidated six-file candidate.

All seven corrections are in docs/orchestrator-prompt.md. Each removes one leading space from an unchanged context line; counts below exclude the single diff context marker:

  • Five Audit G bullet context lines: four source spaces to three.
  • The directory-tree sections/ context line: six source spaces to five.
  • The utilities bullet context line: four source spaces to three.

These corrections preserve all substantive wording, additions and removals. They supplement, rather than replace or reopen, the original six-file wording approval. Ash explicitly excluded saving, repository changes and implementation. The corrected candidate remains unapplied.

Seven proposed whole-file removals

These files were inspected in full at the stated main revision. They are removal candidates under the agreed project direction; no deletion has been performed or separately authorised for implementation by this proposal.

Proposed deletion Evidenced purpose
docs/wordpress-acf-integration.md WordPress/ACF implementation, custom post types, PHP templates, REST endpoints and imports.
docs/wordpress-block-development.md React-to-Gutenberg conversion, block registration and WordPress development workflow.
docs/wordpress-block-mapping.md Portfolio-to-WordPress component mapping and custom-block plan.
docs/wordpress-block-patterns.md WordPress patterns, ACF fields, registration and migration checklist.
docs/wordpress-fse-guide.md Full Site Editing, theme construction, migration and activation.
docs/wordpress-migration-plan.md React-to-WordPress implementation roadmap and hosting alternatives.
docs/theme.json WordPress theme-reference configuration. This is distinct from src/app/theme.json.

These seven candidates are separate from the eight-path contribution already merged through PR #481. Do not repeat the previously completed deletions or rewrites.

Dependencies and unresolved decisions

  • Agree exact handling of references in docs/bem-migration-success.md and docs/modern-react-migration-completion-summary.md before deleting their targets. Preserve historical provenance rather than silently rewriting historical claims.
  • References also exist in prompts/modern-react-migration/04-wordpress-css-alignment.md, reports/2026-03-11-modern-react-migration/04-wordpress-css-alignment.md and tasks/modern-react-migration-tasks.md. These paths are outside the historical docs/ inventory and require separately previewed scope before modification.
  • Renamed headings may change external anchors. No explicit tracked inbound fragments were found during inspection; external inbound links remain unverified.
  • Current src/app/hooks/useContent.ts imports WordPress hooks and sets USE_WORDPRESS = true. Runtime reachability and effect were not assessed. Documentation removal does not remove or disable application integration.
  • Resolve the existing main/develop base-policy conflict before implementation planning. No new branch or base is approved here.
  • Future implementation must recheck source baselines, reference handling, repository requirements, validation and applicable changelog treatment.
  • The historical inventory contains 133 tracked files: 132 Markdown files and one JSON configuration file. Inventory verification does not establish review coverage or approved dispositions.
  • The broader disposition register and original image-assessment requirements remain incomplete. No acceptance checkboxes are changed by this proposal.

Five-file reference-handling and historical-use candidate — wording approved

At 2026-11-11T17:14:58.064Z, Ash approved wording only for the exact consolidated five-file candidate displayed in the continuation chat: sixteen reference changes and five historical-use notices, including the explicitly identified three out-of-inventory files.

Candidate source baseline: main revision fe09574da48ecaff1b41c78ee6c1fa1dbe9bc66b.

Scope File Wording-approved changes
Historical documentation inventory docs/bem-migration-success.md One reference change and one historical-use notice.
Historical documentation inventory docs/modern-react-migration-completion-summary.md Three reference changes and one historical-use notice.
Outside the historical documentation inventory prompts/modern-react-migration/04-wordpress-css-alignment.md One reference change and one historical-use notice.
Outside the historical documentation inventory reports/2026-03-11-modern-react-migration/04-wordpress-css-alignment.md Four reference changes and one historical-use notice.
Outside the historical documentation inventory tasks/modern-react-migration-tasks.md Seven reference changes and one historical-use notice.

The candidate replaces one active local link with a commit-pinned historical-source link and adds pinned source links beside fifteen literal paths. Its five early notices distinguish historical evidence from current instructions, preserve recorded claims and state that the book project will not undertake WordPress implementation. Retirement of the seven target files remains proposed.

Historical paths, metadata, dates, versions, authorship, statistics, completion claims, original imperatives and checkbox states remain unchanged. The notices do not declare unrelated mixed-purpose content obsolete.

This later approval settles wording only for the reference-handling and notice candidate; the earlier dependency bullets are retained as prior context, not a statement that no candidate has subsequently been drafted or wording-approved. External backlinks, source rechecks, base policy and applicable delivery controls remain unresolved.

The exact consolidated patches and notices remain in the continuation chat, “Choose next WordPress documentation scope option”. This summary does not replace those patches, reproduce their full content or approve different wording. The original six-file preview and revision-2 amendments were recovered from “TOA - Plan obsolete portfolio documentation cleanup”.

Ash explicitly excluded saving, repository changes, implementation and all seven proposed deletions. Existing six-file wording approvals remain unchanged. No five-file candidate changes have been applied.

Exclusions and intentional non-changes

  • No application, runtime, dependency, hosting, deployment, shared-governance, manuscript or asset changes.
  • No deletion of src/app/theme.json.
  • No blanket removal of WordPress mentions from biography, company/community history, editorial research or source attribution.
  • No whole-file deletion of generic block/design references merely because their terminology resembles WordPress.
  • No additional image removal; the original excluded image payloads were not visually reassessed.
  • No changes to issue title, status, assignee, labels, project, milestone, relationships or native PR associations.
  • Existing review history, merged-contribution evidence, attachments and unrelated description content remain preserved.

Current state

The six-file candidate, including the seven later approved whitespace-context corrections, and the five-file reference-handling and historical-use candidate are approved for wording only and remain unapplied. The seven whole-file removals remain proposed and unauthorised for implementation.

This proposal section is already saved in the issue description; the former “unsaved issue-description preview” statement was inaccurate. The exact repository patches remain in the source and continuation chats, not reproduced in full here. Recording wording approval or saving this summary does not authorise repository implementation.

Consolidated documentation rewrite drafts

Five historical replacement drafts, consolidated against develop revision 3f583002482d80ffd1910676bcf7c63e13989b20, remain attached unchanged. They superseded the separate 32 previews.

PR #481 subsequently changed the five corresponding documentation paths. Their merged state is recorded above; the attachments are retained as review history, not a new implementation instruction. Their exact byte-for-byte correspondence and historical approval trail were not independently reverified in the branch-strategy assessment.

ebook-preferences.md

TESTING.md

dark-mode-troubleshooting.md

NETLIFY_CACHE_VERIFICATION.md

INTEGRATION-VALIDATION-PLAN.md

Continuation handover — remaining documentation review

pasted.md

Use this attachment as a read-only review brief: reconcile the current documentation inventory with the historical audit, identify overlapping work and prepare a bounded next-batch proposal with exact paths, dispositions, preservation requirements and validation.

Do not repeat the eight-path contribution associated with PR #481 or reopen its settled canonical-brief decision without new evidence. The current issue records that contribution on inspected main but absent from inspected develop; reconcile current refs before relying on the attachment’s develop-based assumptions. No backport is authorised by this handover.

Retrieve the original audit where accessible. Keep historical counts, current inventory counts and unassessed images distinct. Do not reconstruct inaccessible report contents or treat historical validation as current results.

The next deliverable is findings and an exact proposed batch, not implementation. Repository edits, branch creation, commits, pushes, PR creation and record changes require their applicable separate authorisation. Preserve historical evidence, attribution, restricted material and unrelated work.

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

Metadata

Metadata

Assignees

Type

No type

Fields

Priority

Medium

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions