Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Repair book manuscript coherence: canonical metadata, honest claims, template case studies, and reference/path cleanup#1279

Merged
SkBlaz merged 3 commits intomasterSkBlaz/py3plex:masterfrom
copilot/fix-py3plex-manuscriptSkBlaz/py3plex:copilot/fix-py3plex-manuscriptCopy head branch name to clipboard
Mar 21, 2026
Merged

Repair book manuscript coherence: canonical metadata, honest claims, template case studies, and reference/path cleanup#1279
SkBlaz merged 3 commits intomasterSkBlaz/py3plex:masterfrom
copilot/fix-py3plex-manuscriptSkBlaz/py3plex:copilot/fix-py3plex-manuscriptCopy head branch name to clipboard

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 20, 2026

The manuscript had conflicting edition metadata, duplicated citation/back-matter structure, unfinished case-study scaffolds, stale internal/example references, and overclaimed language that weakened technical trust. This PR rewrites those sections into a consistent, citable, reproducible book manuscript with clearer core-vs-advanced flow.

  • Canonical edition metadata + citation unification

    • Standardized book identity to Version 1.1.4 (2025) in front matter/back matter.
    • Consolidated citation guidance into bibliography.rst; removed duplicate citation.rst.
    • Updated index.rst references section to a single bibliography entry.
  • Case-study rescue (no pseudo-results left)

    • Converted incomplete/future-tense case-study text into explicit workflow template framing.
    • Removed fake-result scaffolds (when completed, to complete this case study) and replaced with actionable adaptation guidance.
  • Claim-scope corrections

    • Replaced unsupported wording (runnable and tested, production-ready, publication-ready, full parity, etc.) with scoped, supportable language.
    • Tightened stability wording to backward-compatibility intent within 1.x and explicit deprecation expectations.
  • Structure and narrative flow upgrades

    • Installation chapter now follows one golden path first (venv + pip + verification), with alternatives demoted.
    • Separated DSL essentials from advanced/interface-selection guidance to reduce cognitive overload in core chapters.
    • Replaced recap-heavy chapter endings with synthesis/limitations-oriented closings.
  • Reference/path integrity and appendix de-duplication

    • Removed contradictory repository/example taxonomy blocks in Appendix A.
    • Updated stale example paths to current repository layout (getting_started, network_analysis, dsl_zoo, etc.).
    • Reduced GUI chapter prominence as local/experimental and aligned deployment depth to Appendix B.
  • Guardrail test for manuscript integrity

    • Added tests/test_book_manuscript_integrity.py to enforce:
      • canonical version in front matter,
      • single reference section (no duplicate citation page),
      • removal of stale example path roots,
      • explicit template framing for case study 3.
# tests/test_book_manuscript_integrity.py
def test_book_version_matches_project_version():
    project_data = tomllib.loads((BOOK_ROOT.parent / "pyproject.toml").read_text(encoding="utf-8"))
    project_version = project_data["project"]["version"]
    assert f"version {project_version} (2025)" in _read("front_matter.rst")
    assert f"Version {project_version}" in _read("bibliography.rst")
Original prompt

This section details on the original issue you should resolve

<issue_title>book</issue_title>
<issue_description>You are a ruthless technical-book repair agent. Your task is to FIX the manuscript, not review it.

Operate in implementation mode, not analysis mode.

You are editing a technical book about py3plex that is currently inconsistent, partially unfinished, and too close to exported documentation. Your mission is to transform it into a coherent, citable, technically honest, reproducible technical book manuscript.

Your default behavior:

  • directly rewrite weak text
  • directly fix stale references
  • directly remove hype
  • directly reconcile inconsistencies
  • directly quarantine or complete unfinished material
  • directly improve structure and narrative flow
  • directly emit replacement text, diffs, and rewritten sections

Do not spend time on generic commentary.
Do not praise the manuscript.
Do not produce a high-level review unless needed to justify a specific edit.
Prefer surgical edits, rewritten prose, and concrete replacements.

Core mandate

Repair all of the following:

  1. Conflicting edition metadata

    • Unify release number, version, year, and citation metadata everywhere.
    • Enforce one canonical identity across:
      • cover/front matter
      • title page
      • copyright/imprint page
      • citation instructions
      • appendices
      • repository references
      • any running-text mentions of version/release
  2. Incomplete case studies

    • Find every placeholder, scaffold, pseudo-result, “expected observation,” “when completed,” “to complete this case study,” symbolic variable placeholder, or unfinished interpretation block.
    • For each such section, do exactly one of:
      • fully rewrite it into an honest worked template
      • mark it explicitly as a template/example and remove fake-result language
      • cut it from the main text and relocate it to appendix/online companion
    • Never leave pseudo-results in place.
  3. Overclaimed reproducibility

    • Remove or narrow any unsupported claims such as:
      • runnable
      • tested
      • production-ready
      • publication-ready
      • stable
      • full parity
      • scalable
      • robust
    • Keep only what can be defended by evidence inside the manuscript.
    • Rewrite overclaims into scoped, technically honest language.
  4. Broken chapter references

    • Audit and fix all chapter numbers, appendix references, “see Chapter X” references, further-reading references, and part introductions.
    • Ensure chapter numbering matches the actual TOC and reading order.
  5. Back matter sloppiness

    • Eliminate duplicate bibliography/citation structures.
    • Consolidate references, bibliography, citation guidance, and further-reading material into one clean back matter scheme.
  6. Documentation-export feel

    • Rewrite the manuscript so it reads like a real technical book, not a feature dump.
    • Reduce:
      • repetitive “this chapter covered” summaries
      • feature-list sprawl
      • marketing adjectives
      • repository-tour bloat
    • Increase:
      • conceptual teaching
      • narrative continuity
      • judgment
      • interpretation
      • reader guidance

Editorial rules

  1. Be harsh on the text, not vague.
  2. Every intervention must produce a concrete improvement.
  3. If content is weak, rewrite it.
  4. If content is redundant, cut it.
  5. If content belongs in docs instead of the book, relocate it.
  6. If a claim is stronger than the evidence, weaken the claim.
  7. If two sections contradict each other, resolve the contradiction and standardize the surviving version.
  8. Prefer clean prose over inflated prose.
  9. Prefer one strong example over five shallow feature bullets.
  10. Preserve and strengthen the manuscript’s best assets:
  • conceptual foundations
  • semantic distinctions/pitfalls
  • the DSL as a true differentiator
  • explicit limitations and stability boundaries

What “fix” means

You are not allowed to stop at “this should be improved.”
You must instead do one or more of the following for each problem:

  • provide replacement text
  • provide revised section text
  • provide a patch/diff
  • provide a new chapter ordering
  • provide a rewritten heading/subheading scheme
  • provide corrected cross-references
  • provide replacement claims
  • provide explicit cuts
  • provide exact appendix relocations

Required working method

Follow this sequence:

Phase 1 — Canonicalize the manuscript

  • Establish one canonical:
    • title
    • subtitle if present
    • version/release
    • year
    • citation form
  • Rewrite all conflicting metadata to match the canonical form.

Phase 2 — Purge trust-breaking defects

  • Remove all placeholders, pseudo-results, incomplete scaffold language, stale cross-references, duplicated bibliography structures, and contradictory example-directory descriptions.

Phase 3 — Rewrite for honesty

  • Find every inflated claim and replace it with scope...

💬 Send tasks to Copilot coding agent from Slack and Teams to turn conversations into code. Copilot posts an update in your thread when it's finished.

Copilot AI changed the title [WIP] Fix inconsistencies and improve structure in py3plex manuscript Repair book manuscript coherence: canonical metadata, honest claims, template case studies, and reference/path cleanup Mar 20, 2026
Copilot AI requested a review from SkBlaz March 20, 2026 22:51
@SkBlaz SkBlaz marked this pull request as ready for review March 21, 2026 06:39
@SkBlaz SkBlaz merged commit d1d3c22 into master Mar 21, 2026
33 checks passed
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.

book

2 participants

Morty Proxy This is a proxified and sanitized view of the page, visit original site.