Imported from maboasoft/repository-discovery (SKILL.md). Install upstream with npx skills add maboasoft/repository-discovery. Copyright stays with the author.

Repository Discovery

Public snapshot: July 2026.

This repository publishes a point-in-time version of the Repository Discovery skill. MaboaSoft does not promise that this public copy is actively maintained, complete, or identical to the current internal delivery process. Use it as a reference methodology, not as a support commitment or guarantee of current practice.

Repository Discovery is an engineering methodology for reconstructing product knowledge from repository evidence.

The skill MUST explain the product hidden inside the repository. The skill MUST NOT document source code for its own sake. The skill MUST produce knowledge that helps a reader understand what the system does, who uses it, how work moves through it, what boundaries and constraints exist, what decisions are observable, what risks are supported by evidence, and what remains unknown.

This document is an operational playbook. It is not an AI prompt.

1. Mission

Repository Discovery MUST transform an unfamiliar repository into a business-oriented knowledge base.

The primary outcome is understanding, not volume. Generated documents are only the delivery format. The real work is recovering the product model that the repository implies.

The skill MUST prioritize questions such as:

• What product does this repository implement?
• Who appears to use it?
• Which business capabilities exist?
• How do users or systems accomplish important goals?
• Which external systems, platforms, and operational boundaries matter?
• Which constraints shape the product?
• Which decisions are observable from repository evidence?
• Which risks are supported by evidence?
• Which important questions remain unanswered?

The skill MUST keep non-developer readers in mind while still preserving enough evidence for engineers to verify every important claim.

2. Evolution Model

Repository Discovery SHOULD evolve through repository experiments.

Each real repository analysis SHOULD produce observations that can improve the methodology. The experiments log SHOULD capture what worked, what failed, which heuristics were useful, which unknowns remained unresolved, and which parts of the methodology caused inconsistent output.

Repository Discovery v1 MUST remain LLM-first. The skill MUST NOT require AST parsers, graph databases, custom static-analysis pipelines, or repository indexing systems. Additional tooling SHOULD be introduced only after repeated experiments show a clear limitation that cannot be solved reliably with the methodology alone.

Complexity is earned through observed need.

3. Scope

The skill MUST focus on product knowledge.

In scope:

• product purpose
• roles and actors
• business terminology
• business capabilities
• user and system flows
• external integrations
• business and technical constraints that affect product behavior
• observable product or architecture decisions
• evidence-backed risks
• unknowns
• confidence levels
• consistency review
• Markdown knowledge pages
• D2 diagrams
• Obsidian wiki links

Supported repository types include, but are not limited to:

• web applications
• mobile applications
• backend services
• CLIs
• SDKs
• libraries
• monorepos

Out of scope:

• documenting every class, function, endpoint, module, table, or component
• generating API reference material
• replacing Swagger, OpenAPI, Javadoc, TypeDoc, or similar tools
• generating exhaustive UML
• producing architecture diagrams for every implementation layer
• inventing personas when only roles are recoverable
• inventing business strategy, market positioning, or team motivation
• treating old documentation as authoritative without validation

Implementation details MAY be used as evidence. Implementation details MUST NOT become the main subject unless they directly explain product behavior, product constraints, integrations, risks, or decisions.

4. Guiding Principles

4.1 Business First

The skill MUST describe the product before the implementation.

Repository structure, framework choices, controllers, services, database tables, and modules are evidence sources. They are not the final shape of the knowledge base.

If a page primarily explains code organization rather than product behavior, the page SHOULD be rewritten.

4.2 Understanding Before Writing

The skill MUST build a Product Model before generating final documentation.

The skill MUST NOT generate feature pages, flow pages, or role pages as isolated artifacts before it has a coherent working model of the product.

Draft notes MAY be created during discovery, but final knowledge pages MUST be written after the Product Model is stable enough to explain the repository at a product level.

4.3 Evidence Before Certainty

Important claims MUST be supported by repository evidence whenever practical.

Statements without evidence MUST be written as hypotheses, low-confidence conclusions, or unknowns. Unsupported claims MUST NOT be presented as facts.

4.4 Unknown Is Useful

Unknowns MUST be preserved.

An explicit unknown is better than a confident guess. Unknowns help future contributors know where repository evidence is weak, missing, stale, or contradictory.

4.5 Confidence Is Part of the Claim

Every important conclusion MUST include confidence.

Confidence MUST reflect evidence strength, not the writing quality of the conclusion. Confidence SHOULD be expressed consistently across the knowledge base.

4.6 Documentation Is Evidence, Not Truth

Existing README files, docs, comments, wiki pages, and ADRs MUST be treated as evidence. They MUST NOT be treated as automatically authoritative.

The skill SHOULD read README files early because they often reveal product intent, setup assumptions, supported workflows, and historical vocabulary. The skill MUST validate README claims before trusting them.

Documentation claims SHOULD be compared against implementation, tests, configuration, seed data, UI, and runtime surfaces when those sources are available. If documentation and implementation disagree, the discrepancy MUST be recorded.

4.7 Progressive Discovery

The skill MUST discover knowledge incrementally.

Earlier findings SHOULD become context for later findings. The skill SHOULD move from broad product understanding toward more specific roles, features, flows, integrations, constraints, decisions, risks, and unknowns.

The skill MUST NOT try to generate the entire knowledge base in one pass.

5. Product Model

The Product Model is the central working model used during Repository Discovery.

The skill models the product represented by the repository, not the repository itself. The Product Model SHOULD remain internal during analysis, but its conclusions MUST be reflected in the final knowledge base.

5.1 Product Frame

The Product Model MUST identify the apparent product category and business purpose.

It SHOULD answer:

• What kind of product is this?
• What user or organizational problem does it appear to solve?
• Is it customer-facing, internal, administrative, operational, clinical, financial, educational, content-oriented, infrastructure-oriented, or something else?
• Which repository surfaces most directly reveal product behavior?

The product frame MUST remain tentative until supported by evidence.

5.2 Actors and Roles

The Product Model MUST identify roles rather than personas.

Roles describe what a user or system can do. Personas describe demographic or behavioral archetypes and are usually not recoverable from source code.

A role SHOULD be inferred from permissions, route guards, navigation, user types, admin panels, forms, tests, seed users, translations, onboarding copy, and domain vocabulary.

The skill MUST distinguish between:

• confirmed roles supported by strong evidence
• likely roles supported by partial evidence
• possible roles that should remain unknowns

5.3 Business Entities

The Product Model MUST identify important business entities.

Business entities are product concepts that matter to users or operations. They MAY appear in database schemas, API models, UI labels, reports, exports, translations, fixtures, tests, or documentation.

The skill MUST avoid treating every technical model as a business entity. An entity belongs in the Product Model only when it explains product behavior, user goals, operational workflows, reporting, constraints, or integrations.

5.4 Capabilities

The Product Model MUST group evidence into business capabilities.

A capability is something the product enables a user or another system to accomplish. It is independent of the implementation and MAY span multiple modules, screens, services, jobs, or integrations. Capabilities SHOULD be named from the product point of view.

The skill SHOULD prefer capability names that a Product Manager or Business Analyst would understand. If the repository uses technical names, the skill MAY preserve them as aliases when evidence supports the mapping.

5.5 Flows

The Product Model MUST identify important user and system flows.

A flow describes how a role or external system accomplishes a business goal through ordered steps. Flows SHOULD be reconstructed from UI screens, routes, controllers, state transitions, tests, integration tests, forms, notifications, emails, scheduled jobs, seed data, and documentation.

The skill MUST separate confirmed steps from inferred steps. Inferred steps MUST carry lower confidence or become unknowns.

5.6 Boundaries

The Product Model MUST identify product boundaries.

Boundaries include external systems, authentication providers, payment systems, messaging systems, analytics, file storage, device platforms, deployment environments, data imports, data exports, and operational handoffs.

The skill SHOULD describe each boundary by business purpose first. Implementation mechanism MAY be included only when it clarifies evidence, constraints, risk, or integration behavior.

The Product Model MUST distinguish between:

• confirmed runtime integrations, where repository evidence shows code or configuration actively exchanging data/events with an external system
• configured external boundaries, where provider configuration, credentials, SDK metadata, hostnames, or platform config files exist but runtime usage is not yet proven
• integration unknowns, where an external provider artifact is present but the product behavior, data exchanged, or runtime activation remains unclear

Configured external boundaries MUST NOT be ignored. If a provider-specific config artifact exists, the final knowledge base MUST include either a dedicated Integration page for that provider or a dedicated Unknown explaining why the artifact is not treated as an integration.

5.7 Constraints and Invariants

The Product Model MUST capture constraints that affect product behavior.

Constraints MAY appear as validation rules, hard-coded limits, platform-specific configuration, scheduling rules, feature flags, permission checks, data retention behavior, localization coverage, deployment assumptions, or integration limitations.

An invariant SHOULD be recorded when the repository consistently enforces a rule that appears central to the product.

5.8 Decisions, Risks, and Unknowns

The Product Model MUST carry observable decisions, evidence-backed risks, and unresolved unknowns.

The skill MUST record only observable decisions. It MUST NOT invent motivations.

The skill MUST record only evidence-backed risks. It MUST NOT convert personal preference or aesthetic critique into risk.

The skill MUST preserve unknowns when evidence is absent, contradictory, or too weak to support a conclusion.

6. Repository Discovery Workflow

The workflow MUST proceed from inventory to model to reconstruction to review.

The skill MAY revisit earlier steps when later evidence changes the Product Model. The skill MUST update downstream pages when upstream understanding changes.

6.1 Repository Inventory

The skill MUST begin with Repository Inventory.

Repository Inventory describes what exists in the repository. It is not yet product analysis.

The skill MUST create Inventory.md as the first generated knowledge-base artifact. Inventory.md MUST describe what was examined. Inventory.md MUST contain observations only. Inventory.md MUST NOT contain inferred product knowledge, product conclusions, causal explanations, or confidence claims about product behavior. All conclusions derived from inventory observations MUST appear in the Product Model or later knowledge artifacts.

The inventory SHOULD identify:

• repository shape
• languages
• frameworks
• package and build files
• application entry points
• README files
• existing documentation
• tests
• configuration
• environment files and examples
• assets
• translations and localization files
• seed data and fixtures
• database schemas and migrations
• deployment files
• scripts
• mobile, web, backend, worker, CLI, or service surfaces
• external provider artifacts and hostnames detected
• generated code and build outputs
• generated or vendored areas that should not dominate analysis

Inventory findings SHOULD be brief. They exist to guide analysis, not to become final documentation.

Good inventory observation:

- `mobile/google-services.json` is present.

Bad inventory conclusion:

- The mobile app uses Firebase Analytics.

6.2 Product Model

The skill MUST convert inventory observations into a first working Product Model.

This pass SHOULD identify tentative product frame, roles, business entities, capabilities, flows, integrations, constraints, risks, and unknowns.

The Product Model MUST be treated as provisional until evidence is checked across multiple repository surfaces.

6.3 Knowledge Discovery

The skill MUST investigate product knowledge progressively.

Discovery SHOULD proceed through:

• roles
• glossary
• features
• flows
• integrations
• constraints
• decisions
• risks
• unknowns

The order MAY change when repository evidence clearly suggests a better route, but the skill MUST preserve progressive understanding.

6.4 Canonical Knowledge Registry

Before final pages are generated, the skill MUST establish a Canonical Knowledge Registry.

The registry is the authoritative working list of canonical page names, aliases, page types, and intended output paths. It MAY be internal during drafting, but its results MUST be reflected in index pages and Review.md.

The registry MUST include every accepted:

• glossary term
• role
• feature
• flow
• integration
• constraint
• decision
• risk
• unknown

Each registry entry MUST identify:

• canonical name
• aliases or near-duplicates found in repository evidence
• artifact type
• intended page path
• confidence or evidence status when useful

The skill MUST use canonical names from the registry when writing Obsidian links. The skill MUST NOT create competing canonical names such as Mobile code, Mobile Code, and Setup Code for the same concept. Aliases MUST resolve to one canonical page unless evidence supports separate product concepts.

If a concept is needed by a downstream page but is not strong enough for a canonical page, the skill MUST either remove the concept from the final knowledge graph or create a dedicated Unknown that explains the unresolved terminology or concept boundary.

6.5 Staged Build Order

Final knowledge pages MUST be built in dependency order. Draft notes MAY be exploratory, but final pages MUST NOT be finalized before their upstream canonical concepts are present in the Canonical Knowledge Registry. For core reader vocabulary, glossary term pages and role pages MUST exist before dependent feature and flow pages are finalized.

The required build order is:

1. Inventory.md
2. Product Model
3. Canonical Knowledge Registry
4. Glossary term pages and Glossary.md
5. Role pages
6. Integration pages
7. Constraint pages
8. Feature pages
9. Flow pages
10. Decision pages
11. Risk pages
12. Unknown pages and Unknowns.md
13. Overview and other index pages
14. Review.md and final validation

The skill MAY revisit earlier stages when later evidence changes the Product Model. When an earlier stage changes, every dependent later page MUST be reviewed and updated before final validation.

Flow pages MUST be written after glossary, role, and feature pages exist. Flow pages MUST use canonical glossary, role, feature, integration, constraint, and unknown names through Obsidian wiki links whenever those concepts appear as product concepts.

Feature pages MUST link to canonical roles, flows, integrations, constraints, risks, glossary terms, and unknowns where those relationships are material. Integration, constraint, decision, risk, and unknown pages MUST also use canonical links for product concepts that already exist in the registry.

Cross-links to pages built later in the order are allowed only when the target already exists in the Canonical Knowledge Registry and will be generated before final validation. The final validation MUST fail if any registry-backed link still points to a missing page. Unknown pages MAY be created as soon as they are needed by an earlier stage, but Unknowns.md MUST be finalized after the other canonical pages have been reviewed.

Overview pages MUST be written last. Overview pages MUST summarize and link existing canonical pages rather than introduce new canonical product facts.

6.6 Knowledge Refinement

The skill SHOULD refine discovered knowledge before finalizing pages.

Refinement includes:

• merging duplicate concepts
• selecting canonical names
• updating the Canonical Knowledge Registry
• preserving aliases when useful
• splitting large topics
• downgrading confidence where evidence is weak
• converting unsupported claims into unknowns
• reconciling docs with implementation
• replacing loose product terms with canonical Obsidian links
• checking whether diagrams still match written claims

The skill MUST prefer a smaller accurate knowledge base over a larger speculative one.

6.7 Consistency Review

The skill MUST perform a consistency review before considering discovery complete.

The review MUST check:

• role names
• feature names
• flow names
• glossary terms
• integration names
• canonical registry entries
• Obsidian links
• unlinked canonical glossary terms in feature and flow pages
• duplicate or near-duplicate page names
• repeated claims
• evidence references
• confidence levels
• unknowns
• D2 diagrams
• contradictions between overview pages and detailed pages

Consistency review MUST happen after Knowledge Refinement, not only during writing.

6.8 Rerun Protocol

When Repository Discovery is rerun against an existing knowledge base, the skill MUST treat the run as a refresh of product knowledge, not as a blind rewrite.

The rerun MUST:

• read the existing overview, indexes, and review artifacts before editing generated pages
• read and refresh Inventory.md before revising the Product Model
• reconstruct or refresh the Canonical Knowledge Registry from existing pages before writing dependent pages
• identify whether the user expects a full rebuild, an incremental refresh, or a focused correction
• preserve valid existing pages unless repository evidence or the updated methodology requires changes
• update dependent pages when a concept, integration, risk, constraint, confidence level, or unknown changes
• add new pages for newly discovered first-class concepts instead of hiding them in overview pages
• keep removed or downgraded claims visible as Unknowns when the evidence gap remains useful
• record what was checked, what changed, and what remains unresolved in a final review artifact

If no review artifact exists from a prior run, the rerun MUST create one.

6.9 Stop Conditions

The skill SHOULD stop when:

• Inventory.md records what was examined without product conclusions
• the Product Model explains the product coherently
• the Canonical Knowledge Registry has been established or refreshed
• primary roles are identified or explicitly unknown
• primary capabilities are identified or explicitly unknown
• primary flows are identified or explicitly unknown
• major integrations and boundaries are identified or explicitly unknown
• important constraints, decisions, and risks are recorded with evidence and confidence
• remaining gaps are captured as unknowns
• discovery coverage and conformance are recorded in a review artifact
• additional passes produce little new product knowledge
• dependency-order build and link validation have been completed
• consistency review has been completed

The skill MUST NOT continue by filling weak areas with speculation.

7. Knowledge Reconstruction

Knowledge Reconstruction turns discovered evidence into product knowledge pages.

The skill MUST synthesize, not transcribe. The skill MUST write from the product point of view.

7.1 Roles

Role pages MUST describe what a role can do and why that role matters to the product.

A role page SHOULD include:

• Summary
• Aliases
• Responsibilities
• Available capabilities
• Related flows
• Evidence
• Confidence
• Related
• Unknowns when relevant

The skill MUST NOT invent demographic personas.

7.2 Glossary

Glossary pages MUST define business terminology.

Each glossary term MUST be represented as an individual page.

A glossary term MUST be a business, domain, workflow, regulatory, operational, or product term that helps readers understand the product. The skill MUST NOT create glossary pages for generic UI labels, incidental code names, framework terms, file names, or ordinary technical words unless the repository uses them as product concepts.

Glossary.md MUST act only as an index linking all glossary term pages. Glossary.md MUST NOT be the canonical location for glossary term definitions.

A glossary entry SHOULD include:

• Summary
• Aliases
• Definition
• Related terms
• Where the term appears
• Evidence
• Confidence
• Related

The skill MUST preserve ambiguity when a term has multiple possible meanings.

During draft discovery, temporary grouped glossary notes MAY be used as private working notes only. Final Repository Discovery output MUST NOT group glossary entries in a single document. Before final review, every discovered glossary term MUST be split into its own page, even for small repositories. If a term is too weak, incidental, or technical to deserve its own glossary page, it MUST be removed from the glossary or recorded as an unknown terminology question instead of being left as an inline grouped definition.

7.3 Features

Feature pages MUST describe business capabilities.

A feature page SHOULD include:

• Summary
• Aliases
• Business purpose
• Participating roles
• Related flows
• Related integrations
• Constraints
• Evidence
• Confidence
• Related
• Unknowns when relevant

The skill MUST NOT define features by implementation modules alone.

7.4 Flows

Flow pages MUST describe ordered business journeys.

A flow page SHOULD include:

• Summary
• Aliases
• Business goal
• Participating roles
• Preconditions when known
• Ordered steps
• Decision points when known
• Related features
• Related integrations
• Diagram when useful
• Evidence
• Confidence
• Related
• Unknowns when relevant

The skill MUST mark uncertain or inferred steps clearly.

7.5 Integrations

Integration pages MUST describe external systems by business purpose.

An integration page SHOULD include:

• Summary
• Aliases
• External system
• Business purpose
• Data or events exchanged when known
• Related features
• Related flows
• Constraints
• Risks
• Evidence
• Confidence
• Related
• Unknowns when relevant

The skill MUST NOT describe an integration only as an SDK or package dependency. The skill MUST NOT collapse provider-specific integrations into a generic integration page when the repository identifies a concrete provider.

Examples:

• SparkPost, SendGrid, Mailgun, Postmark, Amazon SES, or SMTP host configuration MUST be represented as provider-specific mail integration pages when provider evidence exists.
• Firebase, Google Services, FCM, Crashlytics, Analytics, or google-services.json / GoogleService-Info.plist MUST be represented as Firebase/Google integration pages or explicit unknowns when runtime usage is unclear.
• S3, Azure Blob Storage, Google Cloud Storage, Stripe, Twilio, Sentry, Datadog, New Relic, OAuth providers, webhook providers, payment processors, analytics platforms, and file storage providers MUST be represented explicitly when evidence exists.

Generic pages such as "Email Delivery", "Analytics", "File Storage", or "Mobile Device Platform" MAY summarize a capability group. They MUST link to concrete provider pages when provider-specific evidence exists.

Provider configuration without proven runtime behavior MUST still produce a page. That page SHOULD be titled as a configured boundary, for example "Firebase Android Configuration", and MUST carry lower confidence plus a related Unknown about runtime use.

7.6 Constraints

Constraint pages MUST describe limitations or rules that shape product behavior.

A constraint page SHOULD include:

• Summary
• Aliases
• Constraint
• Product impact
• Affected roles, features, or flows
• Evidence
• Confidence
• Related
• Unknowns when relevant

The skill SHOULD distinguish product constraints from incidental implementation details.

7.7 Decisions

Decision pages MUST record observable decisions.

A decision page SHOULD include:

• Summary
• Aliases
• Observable decision
• Product or architecture impact
• Evidence
• Confidence
• Related
• Unknowns when relevant

The skill MUST NOT invent rationale. If rationale is not present in repository evidence, it MUST be recorded as unknown.

7.8 Risks

Risk pages MUST describe evidence-backed risks.

A risk page SHOULD include:

• Summary
• Aliases
• Risk
• Product, operational, or delivery impact
• Evidence
• Confidence
• Related
• Unknowns when relevant

The skill MUST avoid subjective risk claims. Risk language MUST be proportional to the evidence.

7.9 Unknowns

Unknown pages MUST preserve unanswered questions.

An unknown SHOULD include:

• Question
• Aliases
• Why it matters
• Current evidence
• What evidence would resolve it
• Related

The skill MUST write unknowns as actionable questions whenever possible.

8. Knowledge Base Structure Rules

The generated knowledge base MUST follow the required document structure.

This section defines the output contract for Repository Discovery. It is a required quality gate, not a style preference.

The repository structure MUST NOT determine the knowledge base structure. Knowledge pages MUST be organized around product concepts rather than implementation artifacts.

Inventory.md MUST exist. Inventory.md MUST be the canonical record of repository surfaces examined during discovery. Inventory.md MUST NOT contain product conclusions. Inventory.md SHOULD include sections for repository shape, scanned paths, ignored paths, entry points, languages, frameworks, documentation, tests, configuration, external provider artifacts detected, generated code, and first-pass repository observations. Inventory.md MUST NOT include a "Product Purpose", "Product Summary", "First Impression", or similar conclusion-oriented section. First-pass repository observations MUST describe observed repository surfaces, not what the product does.

Product conclusions MUST start in the Product Model and continue in canonical knowledge pages. If Inventory.md contains a sentence that explains what the product does, who uses it, how a feature works, or whether an integration is active, that sentence SHOULD be moved to the Product Model or a later page.

Unknowns MUST be written as dedicated pages or as a dedicated Unknowns document. Unknowns MUST NOT be embedded inside unrelated feature, flow, or role pages as the only representation.

Decisions MUST be first-class knowledge artifacts. Decisions MUST NOT be merged into feature, integration, constraint, or risk documents.

Risks MUST be first-class knowledge artifacts. Risks MUST NOT be merged into feature or integration pages except for cross-references.

Constraints SHOULD be represented as dedicated pages unless the repository contains only a very small number of constraints.

Each Role, Feature, Flow, Integration, Constraint, Decision, Risk, and Unknown MUST contain all required sections defined by this methodology.

Combined documents MAY be created during early discovery. Combined documents MUST be split into dedicated pages during Knowledge Refinement before final review.

Glossary entries MUST NOT remain grouped in final output. Each glossary term MUST have a dedicated page with the required glossary-entry sections. Glossary.md MUST be an index and MAY include one-line descriptions only when they do not replace the dedicated glossary pages.

Overview documents MAY summarize knowledge. Overview documents MUST NOT become the canonical location for detailed descriptions.

Every major knowledge artifact MUST be reachable through Obsidian links. The knowledge base MUST avoid duplicate canonical descriptions.

The knowledge base MUST include a final review artifact named Review.md unless the user explicitly requests a different filename. Review.md MUST summarize discovery coverage, important scan boundaries, Canonical Knowledge Registry status, Build Order validation, conformance results, link validation status, known omissions, and unresolved methodology tradeoffs. Review.md MUST NOT become a dumping ground for product facts that deserve first-class pages.

Index pages MUST reflect the Canonical Knowledge Registry. If an index page lists glossary terms, roles, features, flows, integrations, constraints, decisions, risks, or unknowns, each listed item MUST link to the canonical page for that item.

Before finalizing the knowledge base, the skill MUST perform a document-structure conformance review.

The conformance review MUST verify:

• Inventory.md exists and was written before Product Model synthesis
• Inventory.md records observations only and does not contain inferred product knowledge
• required documents exist
• required sections exist
• required links exist
• document naming follows the methodology
• dedicated artifacts have not been merged incorrectly
• the final pages were built or refreshed according to the required Build Order
• the Canonical Knowledge Registry was established or refreshed before dependent pages were finalized
• every glossary term has a dedicated page
• Glossary.md is an index rather than a grouped glossary
• feature and flow pages use canonical glossary, role, feature, integration, constraint, risk, and unknown links where those concepts appear as product concepts
• every external hostname, provider SDK config file, credential-like provider setting, and webhook/API endpoint discovered during inventory is represented by an Integration, Risk, Decision, Constraint, or Unknown page
• concrete providers have not been hidden inside generic integration pages
• configured external boundaries with unclear runtime usage have dedicated Unknowns
• generated, vendored, test-only, docs-only, and example-only surfaces have been classified so they do not create false product integrations
• repository folders have not been converted into knowledge categories by default
• Review.md records that Inventory.md was reviewed for observation-only discipline, what was scanned, what was excluded as noise, which validations were performed, and whether Build Order was satisfied

9. Heuristics

This section is expected to grow continuously based on repository experiments.

Heuristics SHOULD guide investigation. Heuristics MUST NOT override evidence.

9.1 Role Heuristics

Roles are often found in:

• permission checks
• auth logic
• route guards
• navigation menus
• admin panels
• onboarding screens
• seed users
• tests
• translations
• UI copy
• report filters
• audit logs

9.2 Flow Heuristics

Flows are often found across:

• routes
• controllers
• UI screens
• forms
• state transitions
• integration tests
• end-to-end tests
• emails
• notifications
• scheduled jobs
• import and export paths
• success and error messages

9.3 Feature Heuristics

Features are often found in:

• navigation groups
• route clusters
• page titles
• controller groups
• service names
• test suite names
• docs headings
• seed data
• dashboard widgets
• admin sections
• localization keys

9.4 Business Entity Heuristics

Business entities are often found in:

• database schemas
• migrations
• API DTOs
• form labels
• UI tables
• reports
• exports
• fixtures
• translations
• admin pages
• analytics events

9.5 Integration Heuristics

Integrations are often found in:

• environment variables
• config files
• provider-specific config files
• SDK imports
• package/build dependencies
• webhook handlers
• credential names
• hostnames and URLs
• API keys, client IDs, client secrets, tokens, issuer URLs, audience URLs, connection strings, DSNs, and SMTP credentials
• Docker and deployment files
• retry logic
• error handling
• background jobs
• documentation setup steps
• network security configuration

Integration discovery MUST scan every repository surface, not only the apparent main application. For monorepos or multi-module repositories, each backend, frontend, mobile, worker, auth, proxy, database, deployment, and script module MUST be checked for external providers.

Integration discovery MUST classify external references before creating knowledge pages:

• runtime integration: code or configuration shows active data/event exchange with an external system
• configured provider boundary: provider-specific config, credentials, SDK metadata, hostnames, or platform files exist, but runtime use is not proven
• dependency-only provider signal: package/build dependency names a provider, but no product behavior is confirmed
• user-facing external content link: UI opens an external site for support, legal, accessibility, marketing, documentation, or help content
• build, development, or documentation link: setup docs, examples, comments, licenses, schema URLs, package metadata, or developer-only references
• generated or vendored noise: dependency source, compiled platform output, generated build artifacts, lockfile transitive metadata, bundled libraries, or copied third-party source

Runtime integrations and configured provider boundaries MUST be represented by Integration pages or Unknowns. Dependency-only provider signals MUST be represented as low-confidence Integration pages or Unknowns only when the provider may affect product behavior, privacy, deployment, billing, or operations. User-facing external content links SHOULD be grouped into a content-boundary Integration page when they matter to product behavior or user support. Build, development, documentation, generated, and vendored references MUST NOT create product integrations unless another repository surface shows product behavior.

The scan MUST include at least:

• package and build files: package.json, pom.xml, Gradle files, CocoaPods files, Cordova/Ionic config, lockfiles when useful
• runtime config: .env*, application.properties, application.yml, XML config, JSON config, Docker files, Compose files, Kubernetes/Helm/Terraform files
• platform provider files: google-services.json, GoogleService-Info.plist, Firebase config, OAuth client files, service account files
• logging and notification config: SMTP appenders, push notification config, crash reporting config, analytics config
• code references: SDK imports, HTTP clients, webhook controllers, retry queues, background jobs, scheduled jobs, error reporting calls

The scan SHOULD search for provider and integration indicators such as:

firebase|google-services|GoogleService-Info|fcm|crashlytics|analytics
sparkpost|sendgrid|mailgun|postmark|ses|smtp|spring.mail|JavaMailSender
s3|azure|gcp|stripe|twilio|sentry|datadog|newrelic
webhook|api_key|secret|token|client_id|client_secret|dsn|connection_string
oauth|oidc|saml|issuer|audience|callback|redirect_uri

The skill MUST treat each matched provider artifact as a candidate integration. It MAY downgrade confidence when evidence is only configuration, but it MUST NOT silently omit the candidate. If the only evidence is a package dependency with no import, route, component, runtime config, key, or visible behavior, the skill MUST NOT claim runtime integration. It SHOULD create an Unknown only when the dependency points to a meaningful unresolved product boundary.

Mail integrations require special handling:

• A generic "Email Delivery" page MAY describe the product capability.
• Concrete providers or transports such as SparkPost, Amazon SES, SendGrid, Mailgun, Postmark, or an explicit SMTP host MUST have separate integration pages when provider-specific evidence exists.
• If multiple modules configure different mail providers, each provider/module relationship MUST be recorded or captured as an Unknown.

Mobile platform integrations require special handling:

• Local notifications and device APIs MAY belong under a device-platform integration.
• Firebase/Google Services files MUST NOT be treated only as secrets or build artifacts.
• If Firebase runtime usage is unclear, the output MUST include a Firebase configured-boundary page and an Unknown for runtime behavior.

Noise filtering requires special handling:

• The skill SHOULD inspect generated or vendored directories only long enough to identify them as generated or vendored.
• The skill SHOULD exclude node_modules, compiled mobile platform output, generated build directories, bundled third-party libraries, lockfile transitive package metadata, and minified vendor assets from product integration counts unless direct first-party code references them.
• The skill MUST record meaningful exclusions in Review.md so future readers know the scan was intentional.
• The skill MUST NOT let noisy generated surfaces hide first-party configuration files located near them.

9.6 Constraint Heuristics

Constraints are often found in:

• validation rules
• feature flags
• hard-coded limits
• platform-specific configuration
• localization fallbacks
• scheduling logic
• data retention logic
• permission checks
• deployment assumptions
• billing or quota logic

10. Document Standards

Knowledge pages MUST be written in Markdown. Internal links SHOULD use Obsidian wiki links.

10.1 Page Purpose

Each page MUST answer a specific business question.

If a page does not help a reader understand the product, it SHOULD be removed, merged, or rewritten.

10.2 Required Sections

Each major knowledge page MUST include:

• Summary
• Aliases
• Evidence
• Confidence
• Related

Pages SHOULD add specialized sections when useful:

• Responsibilities
• Business purpose
• Participating roles
• Ordered steps
• Integrations
• Constraints
• Risks
• Unknowns

Required sections MUST NOT become empty boilerplate. Aliases SHOULD contain known alternate names. If no meaningful alternate names are found, the section SHOULD state "None found." If evidence is weak, the Evidence section MUST say so.

10.3 Writing Style

The skill MUST write in business language.

The skill SHOULD use short, concrete statements. The skill SHOULD name repository evidence only when it supports a claim. The skill MUST avoid generic filler, implementation walkthroughs, and unsupported product interpretation.

The skill SHOULD write for Product Managers, Project Managers, Business Analysts, Marketing, Solution Architects, CTOs, and new developers.

10.4 Obsidian Wiki Links

The skill MUST use Obsidian wiki links for important knowledge graph connections once the Canonical Knowledge Registry exists.

Use links for:

• [[Role]]
• [[Feature]]
• [[Flow]]
• [[Integration]]
• [[Constraint]]
• [[Decision]]
• [[Risk]]
• [[Glossary Term]]
• [[Unknown]]

Links MUST be meaningful. The skill MUST NOT add links only to create visual density.

When a canonical product concept appears in a dependent page, the first meaningful occurrence in each major section SHOULD be linked. Flow pages MUST link canonical glossary terms, roles, features, integrations, constraints, risks, and unknowns when those concepts are part of the flow. The skill MUST NOT leave a canonical glossary term as plain text in a flow page when the term is being used as a product concept. The skill MUST NOT create links to aliases when a canonical page exists; use [[Canonical Name|Alias Text]] only when the displayed wording needs to match repository language. The skill MUST validate that every wiki link resolves to a generated page or an intentionally documented external note.

10.5 Page Size and Splitting

Each page SHOULD be readable in less than three minutes.

Large topics SHOULD be split when a page contains multiple business questions, multiple unrelated flows, or too many implementation details.

The skill MUST prefer small connected pages over large omnibus documents.

10.6 Status and Review Notes

Pages MAY include status when it improves maintainability.

Useful statuses include:

• Draft
• Evidence-backed
• Conflicting evidence
• Low confidence
• Needs product review

Status MUST reflect analysis state, not writing completeness.

11. Diagram Standards

Diagrams MUST be written in D2. Diagrams SHOULD support understanding, not decoration.

11.1 Diagram Philosophy

Prefer understanding over completeness.

A diagram MUST communicate a product relationship, flow, boundary, or capability structure. The skill MUST NOT draw the whole backend unless the backend boundary itself is the subject.

11.2 When to Diagram

The skill SHOULD create a diagram when visual structure explains the product better than text.

Useful diagram subjects include:

• system overview
• role-feature relationships
• feature maps
• user flows
• integration boundaries
• risk or constraint context

The skill MUST NOT add diagrams only because diagrams are expected.

11.3 Diagram Types

The skill SHOULD choose the smallest diagram type that explains the idea:

• System overview: major product surfaces and external systems
• Role-feature map: which roles use which capabilities
• Feature map: capability groups and relationships
• Flow diagram: ordered journey or process
• Integration map: external system boundaries and data movement
• Constraint or risk context: affected product areas

11.4 D2 Rules

D2 diagrams MUST use stable names and readable labels.

Diagrams SHOULD:

• show external systems explicitly
• avoid implementation clutter
• label business relationships
• preserve product terminology
• keep uncertain edges out of the diagram or mark them clearly
• D2 diagrams SHOULD be embedded in the Markdown page they document. Separate .d2 files SHOULD only be used when the same diagram is referenced by multiple pages.

Diagrams MUST NOT include every class, table, endpoint, or function.

11.5 Diagram Links

Diagram files SHOULD be referenced from related Markdown pages. Markdown pages SHOULD link to diagrams when the diagram adds understanding.

Diagram labels SHOULD align with page names when practical.

11.6 Diagram Complexity

The skill SHOULD prefer multiple small diagrams over one large diagram.

One diagram SHOULD communicate one idea. Crossing edges SHOULD be avoided when practical. Business concerns and implementation concerns MUST NOT be mixed in the same diagram unless the boundary between them is the point of the diagram.

If a diagram requires a long explanation to understand, the diagram SHOULD be simplified or split.

12. Evidence Rules

Evidence connects repository observations to product claims.

The skill MUST preserve enough evidence for important claims to be checked later.

12.1 Evidence Sources

Evidence MAY come from:

• observed product behavior, when available
• source code
• tests
• configuration
• build files
• seed data
• fixtures
• database schemas
• migrations
• routes
• UI copy
• translations
• assets
• documentation
• comments
• deployment files
• scripts

12.2 Evidence Priority

When sources conflict, the skill SHOULD prioritize evidence in this order:

1. Observed product behavior, when available
2. Tests
3. Configuration and build files
4. Existing documentation
5. Comments

Source code MAY support any level in this priority depending on what it demonstrates. For example, source code that directly defines product behavior is stronger than a comment, while unused source code may be weaker than a passing integration test.

12.3 Evidence Strength

Strong evidence usually includes multiple independent repository surfaces that agree.

Confidence SHOULD increase when UI, tests, configuration, source behavior, and docs point to the same conclusion. Confidence SHOULD decrease when evidence comes from only one stale or ambiguous source.

12.4 Conflicting Evidence

Conflicting evidence MUST be recorded.

The skill MUST NOT silently choose the most convenient version. When conflict exists, the claim SHOULD be marked lower confidence or moved to unknowns until resolved.

12.5 Evidence Formatting

Evidence SHOULD be practical and concise.

Evidence notes SHOULD include repository paths when useful. Evidence notes SHOULD explain what the path proves, not merely list files.

Evidence MUST NOT copy full secret values, private keys, access tokens, passwords, signing passwords, API keys, or credential blobs into the generated knowledge base. When credential-like evidence matters, the skill MUST cite the file path and field name or credential type only. If a short non-sensitive identifier is needed to distinguish providers, the skill MAY quote hostnames, provider names, package names, project names, or non-secret IDs.

Example format:

Evidence:
- `web/src/routes.js` defines admin routes for participants, providers, settings, questions, and exports.
- `backend/server/src/main/resources/data/testusers.json` seeds provider and admin-style users.
Confidence: Medium

13. Confidence Rules

Confidence communicates how strongly the repository supports a conclusion.

13.1 Confidence Levels

The skill SHOULD use these confidence levels unless a project defines another scale:

• High: multiple direct evidence sources agree, and the claim is unlikely to change with more analysis
• Medium: evidence supports the claim, but important details are missing, indirect, or only partially confirmed
• Low: evidence is weak, ambiguous, inferred, stale, or contradicted

The skill MAY use percentages only when the project explicitly prefers numeric confidence.

13.2 What Raises Confidence

Confidence SHOULD increase when:

• multiple independent sources agree
• behavior is visible in user-facing surfaces
• tests confirm the behavior
• configuration matches implementation
• docs match implementation
• names are clear and consistent
• the concept appears across UI, data, and flows

13.3 What Lowers Confidence

Confidence SHOULD decrease when:

• evidence appears only in comments
• docs appear stale
• naming is ambiguous
• code appears unused
• tests are absent
• runtime behavior was inferred from static repository evidence without executing the product
• product flow steps are inferred
• documentation and implementation disagree
• related repository areas are missing

13.4 Claim Language

Claim language MUST match confidence.

High-confidence claims MAY be written directly. Medium-confidence claims SHOULD name the evidence boundary. Low-confidence claims SHOULD be written as tentative findings or unknowns.

The skill MUST NOT use confident language for unsupported conclusions. The skill MUST NOT claim that runtime behavior definitely occurs when only static code, dependency, or configuration evidence was inspected. When the application was not run, pages that depend on runtime activation SHOULD say so in Confidence, Unknowns, or Review notes.

14. Unknown Rules

Unknowns are first-class output.

14.1 Unknown Types

The skill SHOULD capture unknowns about:

• product purpose
• roles
• permissions
• flows
• business rules
• integrations
• data ownership
• deployment
• operational processes
• decisions
• risks
• terminology

14.2 Useful Unknowns

An unknown MUST be useful to a future investigator.

Useful unknowns SHOULD include:

• the unresolved question
• why the question matters
• what evidence was checked
• what evidence would resolve it
• related pages

The skill MUST NOT write vague unknowns such as "needs more research" without explaining what needs to be researched.

14.3 Unknown Lifecycle

An unknown SHOULD remain open until repository evidence, stakeholder input, or runtime observation resolves it.

When resolved, the relevant knowledge pages SHOULD be updated. Resolved unknowns MAY be retained as historical notes when they explain a prior ambiguity.

15. Consistency Rules

Consistency makes the knowledge base usable over time.

15.1 Naming Consistency

The skill MUST use one canonical name for each role, feature, flow, business entity, integration, decision, risk, and unknown.

Aliases MAY be recorded when evidence supports them. Aliases MUST NOT replace canonical names. Canonical names MUST match the Canonical Knowledge Registry.

15.2 Link Consistency

Major pages SHOULD link to related pages using Obsidian wiki links.

Important roles, features, flows, integrations, constraints, risks, decisions, and unknowns SHOULD be reachable from related pages. Dependent pages MUST link to canonical pages instead of repeating important product concepts as unlinked plain text. If a product concept is intentionally not linked, the reason SHOULD be that the mention is incidental, not product-meaningful, or the concept was rejected from the registry. Near-duplicate wiki links MUST be resolved before final validation.

15.3 Claim Consistency

Repeated claims MUST agree across overview, role, feature, flow, integration, risk, decision, and unknown pages.

If a claim changes during analysis, all dependent pages MUST be reviewed.

15.4 Confidence Consistency

Similar evidence strength SHOULD produce similar confidence.

The skill MUST NOT mark one weakly supported claim as High confidence while marking comparable claims as Low confidence without explanation.

15.5 Unknown Consistency

Unknowns MUST NOT contradict confident claims elsewhere.

If an unknown overlaps with a confident claim, the skill MUST resolve the conflict by revising the claim, revising the unknown, or recording conflicting evidence.

16. Anti-patterns

The skill MUST avoid these anti-patterns:

• documenting classes instead of product behavior
• organizing knowledge pages around repository folders by default
• generating feature pages before the Product Model exists
• treating README files as authoritative
• hiding uncertainty
• inventing motivations for decisions
• inventing personas from weak role evidence
• describing integrations only by SDK names
• copying secret values into generated documentation
• treating dependency-only provider packages as confirmed runtime integrations
• letting vendored, generated, or minified files dominate product discovery
• reporting subjective preferences as risks
• over-diagramming
• creating large pages that answer many unrelated questions
• mixing business and implementation concerns without a clear reason
• confusing implementation boundaries with product boundaries
• filling unknowns with guesses
• adding Obsidian links that do not express meaningful relationships
• using diagrams as decoration
• presenting stale docs and current implementation as if they agree

If output looks complete but important claims lack evidence, the output MUST be revised.

17. Self-review Checklist

Before considering Repository Discovery complete, the skill MUST perform a self-review.

17.1 Product Understanding

Check:

• Can a non-developer explain what the product does?
• Is the business purpose clear?
• Are the primary product surfaces identified?
• Does the overview avoid implementation-first framing?

17.2 Product Model

Check:

• Are roles, entities, capabilities, flows, and boundaries coherent?
• Are important product terms named consistently?
• Was a Canonical Knowledge Registry established or refreshed before final pages were written?
• Are inferred parts marked with appropriate confidence?
• Does the Product Model explain the repository better than folder structure alone?

17.3 Evidence and Confidence

Check:

• Do important claims include evidence?
• Does evidence explain what it proves?
• Do confidence levels match evidence strength?
• Are weak claims downgraded or moved to unknowns?
• Are runtime claims downgraded when the application was not executed?
• Are credential-like findings cited without copying secret values?

17.4 Coverage

Check:

• Was the required Build Order followed or consciously refreshed after later evidence changed earlier pages?
• Was Inventory.md written first and kept free of product conclusions?
• Are roles covered?
• Is glossary coverage sufficient for domain terms?
• Does every glossary page describe a real product/domain term rather than incidental code vocabulary?
• Are main features covered?
• Are important flows covered?
• Are integrations covered across every module, including proxy/auth/mobile/deployment modules?
• Are concrete providers represented separately from generic integration categories?
• Are provider config artifacts without runtime evidence represented as configured boundaries plus unknowns?
• Are dependency-only provider signals classified without overstating runtime behavior?
• Are user-facing external content links grouped or excluded intentionally?
• Are generated, vendored, docs-only, test-only, and example-only references filtered or classified?
• Are constraints covered?
• Are observable decisions covered?
• Are evidence-backed risks covered?
• Are unknowns captured?
• Are diagrams present where they improve understanding?
• Does Review.md record registry status, Build Order validation, coverage, exclusions, validations, and remaining gaps?

17.5 Consistency

Check:

• Are names consistent?
• Are Obsidian links meaningful and valid?
• Do flow pages link canonical glossary, role, feature, integration, constraint, risk, and unknown pages where relevant?
• Are canonical glossary terms used as product concepts linked in dependent pages?
• Are duplicate aliases or near-duplicate page names resolved to canonical pages?
• Do overview pages and detail pages agree?
• Do diagrams match written pages?
• Are duplicate concepts merged or intentionally separated?

17.6 Practical Usefulness

Check:

• Can a Product Manager understand the product without reading source code?
• Can a Business Analyst identify major roles, features, and flows?
• Can an Architect understand boundaries, constraints, integrations, decisions, and risks?
• Can a new developer use the knowledge base to orient themselves before reading implementation?

17.7 Unknown Review

Check:

• Is each unknown genuinely unknown from current evidence?
• Can it be investigated later?
• Does it state why the answer matters?
• Does it identify what evidence would resolve it?
• Does it contradict another page?
• Should any unknown be converted into a low-confidence claim or resolved finding?

18. Appendix

Examples SHOULD demonstrate the standard without bloating the methodology.

The appendix MAY include:

• recommended repository layout
• example knowledge base
• example D2
• example Markdown

Examples MUST NOT replace the methodology. Templates MUST NOT encourage boilerplate without evidence.